snappshop-mcp: Snapp! Shop MCP server for AI agents

Let your AI agent shop around on Snapp! Shop (اسنپ‌شاپ).
An unofficial, read-only MCP server for Snapp! Shop, the Snapp marketplace in Iran:
search products, compare every seller's price in Toman, filter by specs, read buyer reviews and catch today's flash sales, all 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

For AI agents

• What: unofficial MCP server (model context protocol) for Snapp! Shop (snappshop.ir), a marketplace of many shops and pharmacies in Iran: electronics, phones, health and beauty, home, fashion. Queries in Persian match best; prices in Toman.
• Install: uvx snappshop-mcp or claude mcp add snappshop -- uvx snappshop-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account (it uses the guest session the site gives every visitor). Snapp! Shop only accepts Iranian IPs: run it from Iran without a VPN, or set SNAPPSHOP_MCP_PROXY to an HTTP proxy that exits in Iran. System proxy settings are ignored.
• Access: read-only. No login, basket, orders or payment, so no confirmation is needed before calling any tool. All 13 tools carry readOnlyHint: true.
• Tools: 13: ss_search, ss_suggest, ss_filters, ss_categories, ss_category, ss_brand, ss_product, ss_compare, ss_reviews, ss_similar, ss_seller, ss_promotions, ss_collection. Typical sequence: ss_search -> ss_product (all sellers, cheapest first) -> ss_reviews. Browsing: ss_categories -> ss_filters -> ss_category.
• Ids: product_id (digits) goes to ss_product and ss_compare; id (6 characters) to ss_reviews and ss_similar; seller_id to ss_seller; collection_id to ss_collection.
• Units: prices in Toman, for delivery to Tehran, as the site shows them.
• Use when: comparing prices, sellers, specs and reviews of products sold in Iran, or watching flash sales.
• Do not use when: the user wants to order or pay, or is outside Iran with no Iranian IP or proxy (the site answers HTTP 403).
• Output: compact JSON. Null and empty fields are omitted (a missing rating = not rated). Lists are 12 items per page; the site caps a list at 10,000 items. Reviewer names are left out.
• Machine-readable: server.json and the iran-mcp catalog once the server is listed there.

Why

Snapp! Shop sells one product through many sellers at different prices, warranties and delivery terms. Finding the best offer means opening product pages one by one. An agent with snappshop-mcp reads them all in seconds:

You: Who sells the Samsung Galaxy A07 (64 GB) cheapest on Snapp! Shop, and with what warranty?

Agent: calls ss_search(query="Galaxy A07 64") → ss_product(product="25751584")

Price (Toman)	Seller	Colour	Warranty
44,600,000	دیجی لند سانا	سبز	گارانتی ۱۸ ماهه شرکتی
44,770,000	سام پلاس	بنفش	گارانتی ۱۸ ماهه هماهنگ (داریا همراه)
45,500,000	ویراوین	سبز	گارانتی ۱۸ ماهه شرکتی

12 sellers in total, rating 4.3 from 370 ratings. Want the reviews with ss_reviews?

_{Real tool output from 2026-11-04; prices and stock change all the time. Prices are in Toman.}

What it can do

• Search products by name, with price range, brand, spec, colour, stock, discount and fast-delivery filters
• Compare sellers: every offer of a product with price, discount, stock, warranty, delivery method and seller rating
• Compare products side by side: price, rating and only the specs that differ
• Browse the category tree, brand pages and seller pages; ss_filters shows the real filters of a list
• Read reviews with scores, pros and cons, and find similar products
• Catch deals: flash sales with end times, campaign pages and every product in a promotion
• Read-only by design: no login, no basket, no orders, no payment

Example prompts:

• "Cheapest Samsung phone in stock, with 256 GB storage and a black colour."
• "Compare the Xiaomi Poco X7 Pro and the Galaxy A56: what differs in the specs?"
• "Which seller of this magnesium supplement has the lowest price, and what do buyers say?"
• "What flash sales end tonight on Snapp! Shop?"
• ارزان‌ترین گوشی سامسونگ موجود با حافظه ۲۵۶ گیگابایت را پیدا کن.
• فروشنده‌های این محصول را با قیمت و گارانتی مقایسه کن.
• امروز چه فروش ویژه‌هایی در اسنپ‌شاپ هست؟

Quick start

You need uv and an Iranian IP address (Snapp! Shop blocks foreign IPs; see FAQ). No API key or account.

claude mcp add snappshop -- uvx snappshop-mcp

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

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

codex mcp add snappshop -- uvx snappshop-mcp

[mcp_servers.snappshop]
command = "uvx"
args = ["snappshop-mcp"]

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

Tools

All tools are read-only. Lists return 12 items per page (page starts at 1).

Filters use names, not ids: specs=["حافظه داخلی=256 گیگابایت"], colors=["مشکی"]. Call ss_filters first to see what a category offers.

How it works

The server calls the same JSON API (apix.snappshop.ir) that the Snapp! Shop web app uses, with the guest token the site hands to every visitor. Requests go out with a Chrome TLS fingerprint and the headers the site's own frontend sends, so they look like normal browsing. One shared HTTP client caches reads for 60 seconds, limits concurrency, retries timeouts and server errors, and refuses any host except apix.snappshop.ir.

Nothing is stored and nothing is sent anywhere else. There is no login: the server cannot see or change an account.

Good to know

• Iranian IPs only. From abroad the site answers HTTP 403 ("turn off your VPN"). Use an Iranian connection or SNAPPSHOP_MCP_PROXY.
• Prices are Toman, as the site shows them, for delivery to Tehran. Stock and prices move during the day.
• Totals are capped at 10,000 by the site and can differ by one or two between calls.
• A phrase nothing matches falls back to unrelated products, so check the titles.
• Top-level categories (such as mobile) have no product list: pick a subcategory from ss_categories.
• Reviewer names are not returned.

FAQ

Does it need an API key or an account? No. It uses the guest session every visitor gets.

Can it buy something or add to the basket? No. It is read-only by design.

Why do I get HTTP 403? The site only answers Iranian IPs. Run the server from Iran without a VPN, or set SNAPPSHOP_MCP_PROXY to an HTTP proxy that exits in Iran.

Is this the same as snapp-mcp? No. snapp-mcp covers Snappfood (restaurants) and SnappMarket (groceries); this server covers the Snapp! Shop marketplace.

Which language should I ask in? Persian matches best because titles and specs are Persian; English brand and model names work too.

How do I filter a phone by storage? Call ss_filters(path="mobile/samsung"), then ss_category(path="mobile/samsung", specs=["حافظه داخلی=256 گیگابایت"]).

Configuration

فارسی: سرور MCP اسنپ‌شاپ

claude mcp add snappshop -- uvx snappshop-mcp

Development

git clone https://github.com/sepehr071/snappshop-mcp && cd snappshop-mcp
uv sync
uv run python -m pytest            # offline, against recorded responses
uv run python -m pytest -m live    # real API (needs an Iranian IP)
uv run ruff check .

Tools live in src/snappshop_mcp/shop.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 API 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

• iran-mcp: catalog of all Iranian-service MCP servers
• snapp-mcp: Snappfood and SnappMarket (restaurants and groceries)
• digikala-mcp: Digikala product search and prices
• torob-mcp: price comparison across Iranian shops
• basalam-mcp: handmade and local products on Basalam

Disclaimer

Unofficial and not affiliated with or endorsed by Snapp. It is read-only: it only reads the public endpoints of the snappshop.ir web app, which can change without notice. Please keep request rates reasonable.

Author

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.

License

MIT

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