khanoumi-mcp: unofficial Khanoumi MCP server for Claude, Cursor and Copilot

khanoumi-mcp: Khanoumi MCP server for AI agents 💄

Unofficial, read-only MCP server that lets your AI agent shop for cosmetics and skin care on Khanoumi (خانومی), an Iranian 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, all from Claude, Cursor or Copilot.

Quick start · For AI agents · What it can do · Tools · FAQ · فارسی

For AI agents

What: unofficial MCP server for Khanoumi (khanoumi.com, خانومی), an Iranian cosmetics and skin care shop. Queries work in Persian and English; prices are in Toman.
Install: claude mcp add khanoumi -- uvx khanoumi-mcp (stdio transport, needs uv and Python 3.10+).
Auth: none. Optional KHANOUMI_MCP_PROXY sets an HTTP proxy for requests to khanoumi.com.
Access: read-only. No login, cart, orders or posted reviews, so no write tools exist.
Tools: 12, all prefixed 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.
Use when: comparing cosmetics, skin and hair care prices, shades, ingredients, reviews or today's deals on Khanoumi.
Do not use when: the user wants to buy something (no cart or checkout), or needs an exact shipping quote for an address (that needs a login on the site).
Output: compact JSON. 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 id or slug from search results to kh_product, kh_reviews and kh_similar; pass category_id from kh_categories or kh_filters to kh_browse.
Machine-readable: server.json, and the catalog of all Iranian MCP servers at awesome-iran-mcp (TOOLS.md, servers.json, ).

Why

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?

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)

_{Real tool output from 2026-10-06; prices change all the time. Prices are in Toman.}

What it can do

🔎 Search products by name in Persian or English, with price, discount, stock and a product image URL (image; kh_product adds an images gallery), sponsored items removed
💸 Find the cheapest in-stock match for a keyword, optionally inside one category
🗂️ Browse any category, brand or campaign sorted by price, popularity or date, with price range and filters
🧴 Filter by skin type, hair type, free-from (paraben, sulfate), key ingredients, color and brand
💋 Read full product details: every shade or size with its own price and stock, sellers, gold price breakdown
💬 Check reviews, similar products and the routine products the shop pairs with an item
⚡ Catch deals: the daily pink box with its countdown, featured rows and the current public discount code
🚚 Know the fees: packaging, shipping, returns and payment rules from the official FAQ, plus beauty guides from the blog
🔒 Read-only by design: no login, no cart, no orders, no reviews posted

Quick start

You need uv. No API key or account.

Claude Code

Terminal

claude mcp add khanoumi -- uvx khanoumi-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

config.json

{
  "mcpServers": {
    "khanoumi": { "command": "uvx", "args": ["khanoumi-mcp"] }
  }
}

Cursor

Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json.

VS Code (Copilot agent mode)

Click Install in VS Code above, or add to .vscode/mcp.json:

config.json

{
  "servers": {
    "khanoumi": { "type": "stdio", "command": "uvx", "args": ["khanoumi-mcp"] }
  }
}

Anything else

It's a standard stdio MCP server: run uvx khanoumi-mcp, or pip install khanoumi-mcp and run khanoumi-mcp.

Then just ask:

"Cheapest moisturizer for oily skin under 500,000 Toman, and what do buyers say about it?"
"Which shades of the Golden Rose Sheer Bright lipstick are in stock, and do they cost the same?"
"What's in today's pink box, and is there a discount code?"
ارزان‌ترین شامپوی ضد ریزش سریتا با ارسال به تهران چند درمیاد؟

How it works

text

  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.

Tools

🔎 Find products (7)

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

💋 One product (3)

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
`kh_similar`	Alternatives to a product, or the products the shop pairs with it

📝 Store and blog (2)

Tool	What it does
`kh_store_info`	Packaging cost, shipping fees and times, returns, payment and guarantee rules from the FAQ
`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.

Good to know

Prices are in Toman. final_price is what you pay, price is before discount, discount_pct is a whole percent.
Shades can cost different amounts. A product's 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.
Order cost: items + 20,000 packaging + shipping (119,000 Tehran / Alborz courier, 113,000 post to other provinces on 2026-10-06; free for items tagged "ارسال رایگان", shown as 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.
Sponsored items are removed from search and listings, and 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.
Ratings are 0–5, null when nobody has rated the product yet. Review comments carry no stars.
Persian queries match best (کرم آبرسان, رژ لب), but English brand names work too (cerave, golden rose).

FAQ

Can it place an order for me?

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.

Why does 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.

How do I filter by skin type or ingredient?

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.

I get "Could not reach khanoumi.com"

The server retries a dropped connection once. If it still fails, check your internet connection. System proxy variables are ignored on purpose; set KHANOUMI_MCP_PROXY if you need a proxy.

Claude Desktop says uvx is not found

Use the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.

Is there a Khanoumi API or MCP server for AI agents?

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.

How do I use Khanoumi with Claude, Cursor or Copilot?

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.

Is it official, safe and free?

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.

How do I debug what the agent sees?

Terminal

npx @modelcontextprotocol/inspector uvx khanoumi-mcp

Configuration

Variable	Default	Meaning
`KHANOUMI_MCP_PROXY`	unset	HTTP proxy for every request, e.g. `http://user:pass@host:port`

فارسی: سرور MCP خانومی

khanoumi-mcp یک سرور MCP غیررسمی برای فروشگاه ایرانی خانومی است و به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در خانومی جستجو کند، ارزان‌ترین محصول موجود را پیدا کند، رنگ‌ها و قیمت هر رنگ را ببیند، بر اساس نوع پوست و مو فیلتر کند، نظرات خریداران را بخواند و تخفیف‌های جعبه صورتی و کد تخفیف روز را پیدا کند.

فقط خواندنی است: وارد حساب نمی‌شود، سبد خرید نمی‌سازد، سفارش ثبت نمی‌کند و نظر نمی‌فرستد.
قیمت‌ها به تومان است و محصولات تبلیغاتی (اسپانسری) از نتایج حذف می‌شوند.
روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.

نصب در Claude Code:

Terminal

claude mcp add khanoumi -- uvx khanoumi-mcp

بعد بپرسید: «ارزان‌ترین کرم آبرسان مناسب پوست چرب زیر ۵۰۰ هزار تومان کدام است و خریداران درباره‌اش چه می‌گویند؟»

برای جستجو کافی است محصول یا برند را به فارسی یا انگلیسی بنویسید، مثلاً «ارزان‌ترین ضد آفتاب سینره» یا «cerave».

Development

bash

git clone https://github.com/sepehr071/khanoumi-mcp && cd khanoumi-mcp
uv sync
uv run pytest            # offline, against recorded responses
uv run 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.

Related servers

Asal Banoo MCP server for cosmetics and skin care prices
Shopino MCP server for fashion across thousands of Iranian shops
All Iranian MCP servers: awesome-iran-mcp

If this saves you clicks, a star helps others find it.

Disclaimer

Unofficial and not affiliated with or endorsed by Khanoumi. It uses the public endpoints of the khanoumi.com website, which can change without notice. Please keep request rates reasonable.

License

MIT