iran-tax-mcp: Iranian tax MCP server for AI agents

Let your AI agent answer Iranian tax questions (مالیات) from the tax administration's own public systems.
An unofficial, read-only MCP server over tax.gov.ir, the goods/service ID system stuffid.tax.gov.ir and the tax regulation database regulation.tax.gov.ir:
e-invoice goods IDs and VAT rates, activity codes, property transaction values, tax laws, circulars and rulings, and the official FAQ.

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 public services of the Iranian National Tax Administration (سازمان امور مالیاتی کشور): tax.gov.ir, stuffid.tax.gov.ir and regulation.tax.gov.ir. Answers are Persian text.
• Install: uvx iran-tax-mcp or claude mcp add iran-tax -- uvx iran-tax-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account. Optional IRAN_TAX_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored. The sites often refuse foreign IPs: outside Iran, use a proxy that exits in Iran.
• Access: read-only. No login, filing, invoicing or payment, so no confirmation is needed before calling any tool.
• Tools: 6, all prefixed tx_: tx_goods_search, tx_activity_codes, tx_property_value, tx_regulations_search, tx_regulation_text, tx_faq_search. For a law question, call tx_regulations_search first, then pass the hit's id and type to tx_regulation_text.
• Use when: a company or accountant needs an e-invoice goods/service ID and its VAT rate, an activity code and its VAT stage, the official property value at an address, the text of a tax law article, a circular (بخشنامه) or ruling, or an official FAQ answer.
• Do not use when: the task needs a taxpayer's own data (returns, invoices, debts, economic-code lookups). Those need a login or a captcha and are not offered.
• Output: compact JSON. Dates and years are Jalali (1405/07/27, 1404). Money is rial as integers. Null and empty fields are omitted. Replies stay under ~15 KB: long texts come in parts of 6000 characters, list sizes are capped.
• Network: the first tx_goods_search for a phrase takes 15-30 s (cached for an hour).
• Machine-readable: server.json and the awesome-iran-mcp catalog.

Why

Iranian tax answers live on three different government sites, each with its own forms, postbacks and search screens. Finding the VAT rate of a product means a slow ID search; finding article 169 bis of the direct tax law means scrolling a 1.6 MB page. With iran-tax-mcp an agent runs the search, picks the right document and returns just the part you asked for.

You: What is the VAT treatment of laptops on the e-invoice system?

Agent: calls tx_goods_search(query="لپ تاپ", limit=5)

It returns the best-ranked active general goods IDs with their VAT rate, type and validity dates.

Every reply is trimmed to stay under about 15 KB, so it does not flood the agent's context.

What it can do

• Find e-invoice goods and service IDs (شناسه کالا و خدمات) by description or 13-digit ID, with VAT rate, type and validity
• Look up activity codes (اینتاکد) with VAT stage, business group and the official profit ratios
• Get the official property value (ارزش معاملاتی) and rent value per m², booklet block and row, and the tax offices for a map point
• Search tax laws, regulations, circulars, rulings, opinions, correspondence and glossary, newest first
• Read the full text of one document, or a single article such as ماده 169 مکرر, with the official PDF link
• Search the official FAQ of the tax administration
• Read-only by design: no login, no filing, no payment

Example prompts:

• "Find the e-invoice goods ID and VAT rate for a laptop."
• "Which activity code fits a restaurant, and what are its profit ratios for 1404?"
• "What is the official property value per m² at latitude 35.70, longitude 51.40?"
• "Show article 169 bis (مکرر) of the direct tax law."
• "Latest circulars about VAT on e-invoicing."
• شناسه کالا و خدمات برای لپ‌تاپ چیست و نرخ ارزش افزوده آن چقدر است؟
• متن ماده ۱۶۹ مکرر قانون مالیات‌های مستقیم را بیاور.
• ارزش معاملاتی ملک در این مختصات چقدر است؟

Quick start

You need uv. No API key or account. Outside Iran, see the proxy note in Good to know.

claude mcp add iran-tax -- uvx iran-tax-mcp

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

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

codex mcp add iran-tax -- uvx iran-tax-mcp

[mcp_servers.iran-tax]
command = "uvx"
args = ["iran-tax-mcp"]

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

Tools

All 6 tools are annotated readOnlyHint: true.

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  iran-tax-mcp  (runs on your machine)
      │
      │  HTTPS
      ├──────▶  tax.gov.ir              activity codes, property values, FAQ
      ├──────▶  stuffid.tax.gov.ir      goods/service IDs and VAT
      └──────▶  regulation.tax.gov.ir   laws, circulars, rulings

iran-tax-mcp runs locally and reads the same public pages and endpoints the three sites use. It has no hosted server in between and no API key. Requests go out through a Chrome-impersonating client, at most 4 at a time with a little jitter, retried up to twice on timeouts, network errors, 5xx and 429. It only talks to the allowed tax hosts and only reads.

Good to know

• Network: these sites timed out through a Turkish proxy exit and answered directly from an Iranian connection. Outside Iran, set IRAN_TAX_MCP_PROXY to an HTTP proxy with an Iranian exit. System proxy variables are ignored on purpose.
• Slow first goods search: the ID system builds a file for each search (15-30 s for a broad phrase such as «لپ تاپ», which has tens of thousands of rows). The server downloads and ranks it (active general IDs first) and keeps it for an hour. Replies are capped at 20 rows.
• Activity codes: the two numeric columns are profit ratios (نسبت سود فعالیت, نسبت سود ناویژه به فروش), not tax rates. The commercial/non-commercial switch (تجاری / غیرتجاری) has no "all" option.
• Property values: the result is the official transaction value for a point, for a chosen year.
• Regulation text: long documents come in parts of 6000 characters; ask for the next part, or for a single article. Documents are cached for an hour.
• Units: years and dates are Jalali, money is rial as integers.
• What it does not do: no economic-code (شماره اقتصادی) or invalid-company lookup, no certificates, no returns, invoices or payments, no login and no captcha solving.

FAQ

npx @modelcontextprotocol/inspector uvx iran-tax-mcp

Configuration

فارسی: سرور MCP مالیات ایران

claude mcp add iran-tax -- uvx iran-tax-mcp

Development

git clone https://github.com/sepehr071/iran-tax-mcp && cd iran-tax-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q          # offline unit tests
uv run python -m pytest -m live -q  # calls the real tax sites, needs an Iranian connection
uv build

Tools live in src/iran_tax_mcp/ (goods.py, taxgov.py, regulation.py); each is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome.

Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions publishes to PyPI.

Related servers

• awesome-iran-mcp: catalog of all Iranian-service MCP servers
• qavanin-mcp for Iranian laws and regulations
• iran-news-mcp for Iranian news
• tgju-mcp for dollar, gold and coin prices
• tsetmc-mcp for the Tehran Stock Exchange

Disclaimer

Unofficial and not affiliated with or endorsed by the Iranian National Tax Administration (سازمان امور مالیاتی کشور). It is read-only and uses public pages of tax.gov.ir, stuffid.tax.gov.ir and regulation.tax.gov.ir, which can change without notice. Information is for reference only and is not tax or legal advice.

License

MIT