AGENTS.md

Guide for AI agents using or working on iran-mcp: 77 MCP servers for Iranian websites, 994 tools in total. 68 are Python packages on PyPI, run as stdio servers with uvx <package>; all of them are unofficial except exiryab-mcp, ExirYab's own server on its public API. Two are hosted by their sites: pasavard-mcp (https://pasavard.ir/api/mcp, no sign-in) and swapwallet-mcp (https://swapwallet.app/mcp, OAuth sign-in).

Pick a server

For the best price, query every server in a category (all doctor servers, all travel servers) and compare. Full tool list: TOOLS.md. Machine-readable catalog with env vars: servers.json.

Install

claude mcp add digikala -- uvx digikala-mcp          # Claude Code

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

SwapWallet is hosted, so it is added by URL: claude mcp add --transport http swapwallet https://swapwallet.app/mcp. Other clients take the URL in their own shape; its skill and its setup for each client list them. The user then signs in with OAuth, in the client: Claude Code doesn't open a browser by itself, so tell the user to run /mcp, pick the server and choose Authenticate. Pasavard is hosted too, with no sign-in: claude mcp add --transport http pasavard https://pasavard.ir/api/mcp.

As Claude Code plugins (MCP server plus a skill with usage rules), from the iran-mcp marketplace:

claude plugin install digikala --marketplace sepehr071/iran-mcp     # one server
claude plugin install iran-all --marketplace sepehr071/iran-mcp     # all read-only site servers

Bundles: iran-all, iran-food, iran-shopping, iran-beauty, iran-fashion, iran-classifieds, iran-cars, iran-travel, iran-maps, iran-health, iran-books, iran-learning, iran-jobs-bundle, iran-freelance, iran-software, iran-prices, iran-stocks, iran-economy, iran-law. Skills only, for any agent: npx skills add sepehr071/iran-mcp.

The server key in config is the package name without -mcp. .mcp.json holds all 77. Requires uv (pasavard-mcp and swapwallet-mcp don't). Add only the servers the task needs: each one adds 3 to 31 tools.

Rules every server follows

• Prices are Toman. Convert before comparing with any Rial figure from elsewhere. Exceptions: tsetmc-mcp, ifb-mcp, ime-mcp and cbi-mcp quote Rial; codal-mcp reports amounts as published, usually million Rial; fipiran-mcp gives NAV in Rial per unit and fund sizes in billion Toman; milligold-mcp gives Rial per milligram, Rial per gram and Toman per gram.
• Site servers are read-only: no login, basket, booking, order or payment. Hand the user the link to buy.
• okala-mcp has an optional OTP login (ok_login), read-only, only for text search. Ask the user first.
• pasavard-mcp store links are affiliate links: say so when you share one. cashback_url returns part of the commission after a one-time phone sign-in on pasavard.ir; buy_url goes straight to the store.
• payping-mcp (PAYPING_TOKEN) and bale-mcp (BALE_BOT_TOKEN) write to the user's own account. Confirm with the user before any payping_create_*, payping_send_invoice, bot_send_*, bot_edit_message or bot_delete_message call.
• swapwallet-mcp acts on the user's own SwapWallet account. Its request_* tools only file a request that the user approves or cancels in Telegram within 15 minutes: tell them so, then call get_action_request, and never say a swap, transfer or withdrawal happened before it reports EXECUTED. Confirm a crypto withdrawal's network and address with the user first. Its skill covers the rest, including the MCP_TELEGRAM_NOT_LINKED and MCP_TWO_FACTOR_ACTIVE errors.
• Package servers, on timeouts or HTTP 403 outside Iran: set the server's <NAME>_MCP_PROXY env var (names in servers.json).
• Package servers call undocumented site APIs that can change or rate-limit. Keep request rates low. exiryab-mcp uses ExirYab's public API, limited to 60 requests per minute per IP.
• 30book-mcp is slow (2 to 5 s per list), and so is rrk-mcp (up to 10 s per search). flytoday-mcp searches are rate-limited per IP. codal.ir blocks an IP for up to an hour after a burst: keep codal-mcp calls few.
• amar-mcp, fipiran-mcp, ifb-mcp, ime-mcp and jobinja-mcp answer only Iranian connections; outside Iran set their proxy variable.

Working on this repo

servers/<name>-mcp/   git submodule, one per server (own repo, own issues, own releases)
scripts/catalog.py    rebuilds servers.json, TOOLS.md, .mcp.json, plugins/ and .claude-plugin/ from the submodules
plugins/              one Claude Code plugin per server (MCP server + skill) and bundle plugins (generated)
.claude-plugin/       marketplace.json for the `iran-mcp` plugin marketplace (generated)
PLUGINS.md            plugin layout, agent compatibility, and how a server release reaches users
scripts/banner.py     redraws the banners, social.svg and the release-<version> banners from servers.json
assets/               banners (generated)
README.md / README.fa.md   English (default) and Persian docs; keep both in sync

• Update servers: git submodule update --init --remote && python scripts/catalog.py && python scripts/banner.py, then commit the new pins and generated files.
• Never edit servers.json, TOOLS.md, .mcp.json, plugins/, .claude-plugin/ or the banners by hand. Skill text comes from skill(), USE and NOTES in scripts/catalog.py, except the rules of a server whose repo ships its own skills/<key>/SKILL.md, which come from that file. Check with claude plugin validate ..
• Add a server: git submodule add https://github.com/sepehr071/<name>-mcp servers/<name>-mcp, add it to SERVERS in scripts/catalog.py (and to GROUPS in scripts/banner.py if its category is new), run both scripts, add a row to both READMEs and the table above. Update the 77 / 994 counts written in both READMEs.
• Add a hosted server: git submodule add <its repo> servers/<name>-mcp and an entry in REMOTE in scripts/catalog.py, then the same GROUPS, README, table and count steps. Its repo needs an MCP Registry server.json with remotes (name, version, description, repository), and the server must publish a server card at <origin>/.well-known/mcp/server-card.json with its tools (with annotations) and authentication. catalog.py reads the tools from the card, marks the server read-only only when it needs no sign-in and every tool is readOnlyHint, and stops on any sign-in other than OAuth.
• Code changes to a server belong in that server's repo. Inside one: uv sync, uv run ruff check ., uv run pytest -q (offline), uv run pytest -m live -q (real site).
• Release a server: bump version in its pyproject.toml, server.json and its own entry in uv.lock (uv lock --check passes), push a v* tag; CI publishes to PyPI, the MCP Registry and GitHub Releases. A README change reaches PyPI only with a release. Then re-pin the submodule here and rerun catalog.py.
• The repo is sepehr071/iran-mcp, renamed from awesome-iran-mcp on 2026-10-23; old URLs redirect. Use the new name in every link. A local checkout may still sit in an awesome-iran-mcp folder.