khanoumi-mcp
Advanced tools
Unofficial read-only MCP server for Khanoumi: search cosmetics, skin and hair care and perfume, compare prices, shades and reviews, find deals.
Let your AI agent shop for cosmetics and skin care on Khanoumi (خانومی).
An unofficial, read-only MCP server for Khanoumi, an Iranian online beauty store: search makeup, skin and hair care and perfume,
compare real prices and shades, filter by skin type, read reviews and catch today's pink-box deals, from Claude, Cursor or Copilot.
For AI agents · Why · What it can do · Quick start · Tools · How it works · Good to know · FAQ · Configuration · فارسی · Development · Related
uvx khanoumi-mcp or claude mcp add khanoumi -- uvx khanoumi-mcp. Transport: stdio. Needs uv (Python 3.10+).KHANOUMI_MCP_PROXY (HTTP proxy URL, or a comma-separated list) for requests to khanoumi.com; system proxy settings are ignored.kh_. Start with kh_find_cheapest, kh_search, kh_product, kh_browse or kh_store_info.
Typical sequence: kh_find_cheapest → kh_product → kh_reviews.final_price is what the buyer pays, price is before discount, discount_pct is a whole percent, ratings are 0-5 or null. Pass the product slug (or its trailing id) from results to kh_product, kh_reviews and kh_similar; pass category_id from kh_categories or kh_filters to kh_browse.server.json and the catalog of all Iranian MCP servers at iran-mcp (TOOLS.md, servers.json, llms.txt).Khanoumi lists about 67,000 beauty products from 3,200 brands. A search for "sunscreen" mixes sponsored
items, out-of-stock products and shades with different prices, and the fees only show up at checkout.
Finding the cheapest one you can actually order, and what it costs delivered, means a lot of clicking.
An agent with khanoumi-mcp does that in seconds:
You: Cheapest Cinere sunscreen I can order now, delivered in Tehran?
Agent: calls
kh_find_cheapest(query="ضد آفتاب سینره")→kh_store_info(topic="delivery")
Total Product Price 924,000 کرم ضد آفتاب بی رنگ با SPF45 مناسب آقایان 785,000 (25% off) 926,500 کرم ضد آفتاب بی رنگ Oil Free SPF50 مناسب پوست چرب 787,500 (25% off) 964,000 ضد آفتاب رنگی +SPF60 مات کننده پوست چرب (2 shades) 825,000 (25% off) Totals include 20,000 packaging and the 119,000 Tehran courier fee. The SPF45 for men is cheapest; if you have oily skin the Oil Free SPF50 costs only 2,500 more. Want me to check which tinted shade is in stock with
kh_product?
Real tool output from 2026-10-06; prices change all the time. Prices are in Toman.
image; kh_product adds an images gallery), sponsored items removedYou need uv. No API key or account.
claude mcp add khanoumi -- uvx khanoumi-mcp
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"khanoumi": { "command": "uvx", "args": ["khanoumi-mcp"] }
}
}
Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json.
Click Install in VS Code above, or add to .vscode/mcp.json:
{
"servers": {
"khanoumi": { "type": "stdio", "command": "uvx", "args": ["khanoumi-mcp"] }
}
}
codex mcp add khanoumi -- uvx khanoumi-mcp
Or in ~/.codex/config.toml:
[mcp_servers.khanoumi]
command = "uvx"
args = ["khanoumi-mcp"]
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"khanoumi": { "command": "uvx", "args": ["khanoumi-mcp"] }
}
}
Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It's a standard stdio MCP server: run uvx khanoumi-mcp, or pip install khanoumi-mcp and run khanoumi-mcp.
Then just ask:
Products are identified by the slug of their page (for example golden-rose-sheer-bright-lipstick-112222); its trailing number also works. Always pass the full slug from a reply. Lists return compact product cards with price, discount, stock, rating, image and url.
| Tool | What it does |
|---|---|
kh_search | Search by keyword: price, discount, stock, plus matching categories and brands |
kh_find_cheapest | Cheapest in-stock matches for a keyword, one flat list sorted by payable price |
kh_browse | A category, brand or campaign tag sorted by price / popularity / date, with price range and filters |
kh_filters | Sub-categories, brands, colors, skin / hair type and ingredient filters, price range and stock counts of a listing |
kh_categories | Category tree with ids, paths and product counts |
kh_brands | Find brands and their slugs |
kh_deals | Today's pink box and featured deals, biggest discount first, with the countdown and the public discount code |
| Tool | What it does |
|---|---|
kh_product | Price, discount, every shade / size / seller with its own price and stock, rating, attributes, description |
kh_reviews | Customer comments, newest first, with verified-buyer flag and photos (text cut to 400 characters; full_text=true for all) |
kh_similar | Alternatives to a product, or the products the shop pairs with it |
| Tool | What it does |
|---|---|
kh_store_info | Packaging cost, shipping fees and times, returns, payment and guarantee rules from the FAQ (topic=all clips answers to 300 characters; full_text=true for all) |
kh_blog_search | Buying guides, routines and ingredient explainers from the Khanoumi magazine |
All 12 tools are annotated readOnlyHint: true and return compact structured JSON, so they don't flood the agent's context.
AI agent (Claude, Cursor, Copilot, ...)
│
│ MCP over stdio
▼
khanoumi-mcp (runs on your machine)
│
│ HTTPS
└──────▶ www.khanoumi.com JSON API, FAQ page, blog
khanoumi-mcp runs locally and calls the same public endpoints the khanoumi.com website uses.
There's no hosted server in between, no API key, and nothing about you is sent anywhere else.
Requests go out through a Chrome-impersonating HTTP client, at most 2 at a time with a short random pause, and the
client refuses to follow a redirect to any host other than www.khanoumi.com. Slow-changing answers (FAQ, category tree) are cached for 5 minutes.
final_price is what you pay, price is before discount, discount_pct is a whole percent. final_price is null for an out-of-stock item.final_price is its cheapest shade or size; kh_product lists each variant with its own price, stock (in_stock) and maximum quantity per order.FreeShipping in a product's badges). kh_store_info reads the current fees. The exact quote per address needs a login, so it isn't available here.total counts only real matches. Pages follow on from each other without gaps or repeats, which the site's own pager doesn't manage when ads are on the page.kh_search re-sorts the first 300 matches by payable price itself.null when nobody has rated the product yet. Review comments carry no stars.کرم آبرسان, رژ لب), but English brand names work too (cerave, golden rose).kh_blog_search sparingly. Keep overall request rates low.KHANOUMI_MCP_PROXY if you need one.Khanoumi doesn't publish an official API for agents. khanoumi-mcp is an unofficial MCP server that wraps the public
endpoints of khanoumi.com as 12 read-only tools, so any MCP client can search and compare products.
Install the server once (see Quick start), then ask in plain language, in Persian or English. In Claude Code
the install is claude mcp add khanoumi -- uvx khanoumi-mcp.
It is unofficial and free (MIT). It is read-only, needs no account or API key, and runs on your machine with no hosted server in between.
No, and that's deliberate. It has no login and never touches the cart, order, payment, wishlist, notify-me or review endpoints. The agent finds the best option; you buy it on khanoumi.com.
kh_find_cheapest skip some items?It keeps only items you can order now whose Persian or English title or brand contains every word of your query
(match_all_words: false turns that off). It scans the first 300 results, cheapest first; complete: false in the reply
means more matches lie past that, so raise scan (up to 900) or narrow with category_id. kh_search shows everything.
Call kh_filters for the category (for example category_id: 145, moisturizers) and pass the keys you want to
kh_browse, e.g. facets: ["facetKey.skin-type:oily"]. Several facets must all match; several brands or colors match any.
The server retries a dropped connection up to twice. If it still fails, check your internet connection. System proxy
variables are ignored on purpose; set KHANOUMI_MCP_PROXY if you need a proxy.
Install the optional browser fallback: pip install "khanoumi-mcp[browser]" (or uvx --from "khanoumi-mcp[browser]" khanoumi-mcp),
then run patchright install chromium. It opens the site once in a headless browser only when a bot-check page appears.
uvx is not foundUse the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
npx @modelcontextprotocol/inspector uvx khanoumi-mcp
| Variable | Default | Meaning |
|---|---|---|
KHANOUMI_MCP_PROXY | unset | HTTP proxy for every request, e.g. http://user:pass@host:port; a comma-separated list is used one at a time (next one after a block or connect error) |
khanoumi-mcp یک سرور MCP غیررسمی و فقطخواندنی برای فروشگاه اینترنتی خانومی است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد در خانومی جستجو کند، ارزانترین محصول موجود را پیدا کند، رنگها و قیمت هر رنگ را ببیند، بر اساس نوع پوست و مو فیلتر کند، نظرات خریداران را بخواند و تخفیفهای جعبه صورتی و کد تخفیف روز را پیدا کند.
چه کارهایی میکند
نکتهها
کلیدواژهها: خانومی، khanoumi، سرور MCP خانومی، خرید لوازم آرایشی، مراقبت از پوست، مراقبت از مو، عطر و ادکلن، ضد آفتاب، شامپو، کرم آبرسان، مقایسه قیمت، ارزانترین قیمت، جعبه صورتی خانومی، کد تخفیف، فروشگاه اینترنتی.
نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add khanoumi -- uvx khanoumi-mcp
در Claude Desktop، Cursor و بقیه برنامهها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسشها
برای جستجو کافی است محصول یا برند را به فارسی یا انگلیسی بنویسید، مثلاً «رژ لب» یا «cerave».
git clone https://github.com/sepehr071/khanoumi-mcp && cd khanoumi-mcp
uv sync
uv run python -m pytest # offline, against recorded responses
uv run python -m pytest -m live # real khanoumi.com
uv run ruff check .
Tools live in src/khanoumi_mcp/catalog.py, product.py and info.py; each is a typed async function with a
docstring that tells the agent when to use it. Issues and PRs are welcome, especially new tools and fixes for site changes.
Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions tests,
publishes to PyPI and the MCP Registry, and creates the GitHub Release.
Unofficial and not affiliated with or endorsed by Khanoumi. It is read-only and uses the public endpoints of the khanoumi.com website, which can change without notice. Please keep request rates reasonable.
Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp. If this saves you time, a star on the repo helps other people find it.
If this saves you clicks, a star helps others find it.
FAQs
Unofficial read-only MCP server for Khanoumi: search cosmetics, skin and hair care and perfume, compare prices, shades and reviews, find deals.
The pypi package khanoumi-mcp receives a total of 568 weekly downloads. As such, khanoumi-mcp popularity was classified as not popular.
We found that khanoumi-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.