This is an unofficial, read-only MCP server for querying Iranian tax public systems through six tools.
Search e-invoice goods/service IDs (شناسه کالا و خدمات) by description or 13-digit ID, including VAT rate, type, validity, and active general IDs.
Look up tax activity codes (اینتاکد) with VAT status, business group, and official profit ratios by year.
Get official property transaction and rent values per m² for a map coordinate and Jalali year, plus booklet block/row and tax offices.
Search tax laws, regulations, circulars, rulings, opinions, correspondence, and glossary entries, newest first.
Read the full text of a tax document or a specific article/section, with metadata and official PDF link.
Search the tax administration’s official FAQ and return matching questions with links.
Use it for public reference data only: no login, taxpayer data, returns, invoicing, payments, or captcha-based lookups.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@iran-tax-mcp What's the VAT rate for laptop e-invoice goods IDs?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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
iran-mcp catalog.
Related MCP server: tsetmc-mcp
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.
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."
شناسه کالا و خدمات برای لپ‌تاپ چیست و نرخ ارزش افزوده آن چقدر است؟
متن ماده ۱۶۹ مکرر قانون مالیات‌های مستقیم را بیاور.
ارزش معاملاتی ملک در این مختصات چقدر است؟
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-mcpSettings → Developer → Edit Config, then add:
{
"mcpServers": {
"iran-tax": { "command": "uvx", "args": ["iran-tax-mcp"] }
}
}Add the Claude Desktop block above to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Click Install in VS Code above, or add to .vscode/mcp.json:
{
"servers": {
"iran-tax": { "type": "stdio", "command": "uvx", "args": ["iran-tax-mcp"] }
}
}codex mcp add iran-tax -- uvx iran-tax-mcpOr in ~/.codex/config.toml:
[mcp_servers.iran-tax]
command = "uvx"
args = ["iran-tax-mcp"]Add to ~/.gemini/settings.json:
{
"mcpServers": {
"iran-tax": { "command": "uvx", "args": ["iran-tax-mcp"] }
}
}Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It is a standard stdio MCP server: run uvx iran-tax-mcp, or pip install iran-tax-mcp and run iran-tax-mcp.
Tool | What it does |
| E-invoice goods/service IDs (شناسه کالا و خدمات) with VAT rate, type and validity, by description or 13-digit ID ( |
| Activity codes (اینتاکد) with VAT stage, business group and official profit ratios ( |
| Official property transaction value (ارزش معاملاتی) and rent value per m², booklet block and row, and the tax offices for a point ( |
| Search tax laws, regulations and circulars, rulings, opinions, correspondence and glossary, newest first ( |
| Full text of one document, or one article of it such as |
| The tax administration's FAQ: matching questions with links ( |
All 6 tools are annotated readOnlyHint: true.
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, rulingsiran-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.
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.
The tax administration's public sites have no documented open API for these lookups. iran-tax-mcp is an unofficial MCP server with 6 read-only tools that reads the public pages of tax.gov.ir, stuffid.tax.gov.ir and regulation.tax.gov.ir and returns compact JSON for AI agents.
Often not: Iranian government sites drop many foreign connections. It was built and tested on a direct Iranian connection. Set IRAN_TAX_MCP_PROXY to a proxy in Iran if calls fail to connect.
On tax.gov.ir those forms need a captcha, and the e-invoice API needs the taxpayer's signed key. This server only uses what is public without either.
The ID system answers a search by building a file (15-30 s for a broad phrase such as «لپ تاپ»). The server downloads it once, ranks it (active general IDs first) and keeps it for an hour, so repeats are fast.
Call tx_regulations_search to find the document, then tx_regulation_text with its id and type, and article set to something like ماده 169 مکرر.
No. The two numeric columns are the official profit ratios (نسبت سود فعالیت and نسبت سود ناویژه به فروش).
No. It has no login and no write calls, it only reads public information. Nothing it returns is tax or legal advice.
npx @modelcontextprotocol/inspector uvx iran-tax-mcpVariable | Default | Meaning |
| unset | Optional HTTP proxy URL for requests to the tax sites; system proxy settings are ignored. A comma-separated list is used one at a time: the next proxy takes over when one is blocked or cannot connect |
iran-tax-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای خدمات عمومی سازمان امور مالیاتی کشور است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در سامانه‌های tax.gov.ir، stuffid.tax.gov.ir و regulation.tax.gov.ir جست‌وجو کند.
چه کارهایی می‌کند
شناسه کالا و خدمات (صورتحساب الکترونیکی، سامانه مودیان) و نرخ ارزش افزوده، با توضیح کالا یا شناسه ۱۳ رقمی.
کد فعالیت (اینتاکد) با مرحله ارزش افزوده و نسبت سود رسمی.
ارزش معاملاتی املاک و ارزش اجاره هر متر مربع بر اساس مختصات.
قوانین، بخشنامه‌ها، دستورالعمل‌ها و آرای مالیاتی از سامانه جامع مقررات مالیاتی، با متن کامل یا یک ماده مشخص مثل «ماده ۱۶۹ مکرر».
پرسش‌های متداول سازمان امور مالیاتی.
نکته‌ها
فقط خواندنی است: وارد حساب نمی‌شود، اظهارنامه نمی‌دهد و پرداخت انجام نمی‌دهد. مشاوره مالیاتی یا حقوقی نیست.
استعلام شماره اقتصادی و شرکت‌های نامعتبر ارائه نمی‌شود (کپچا یا ورود لازم دارد).
سال و تاریخ شمسی است و مبالغ به ریال.
جست‌وجوی اول شناسه کالا ۱۵ تا ۳۰ ثانیه طول می‌کشد و بعد یک ساعت ذخیره می‌شود.
این سامانه‌ها اغلب IP خارجی را قبول نمی‌کنند؛ از اینترنت ایران استفاده کنید یا متغیر IRAN_TAX_MCP_PROXY را روی یک پراکسی HTTP با خروجی ایران بگذارید.
کلید API لازم نیست و روی سیستم خود شما اجرا می‌شود.
نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add iran-tax -- uvx iran-tax-mcpدر Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسش‌ها
«شناسه کالا و خدمات لپ‌تاپ و نرخ مالیات بر ارزش افزوده آن چیست؟»
«متن ماده ۱۶۹ مکرر قانون مالیات‌های مستقیم را بده.»
«آخرین بخشنامه‌های مربوط به صورتحساب الکترونیکی کدام‌اند؟»
«کد اینتاکد برای رستوران چیست؟»
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 buildTools 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.
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
Listed on mcpfarsi.ir, the Persian MCP marketplace
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.
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.
Find tax activity codes (کد فعالیت / اینتاکد) with their VAT status and official profit ratios.
Source: tax.gov.ir SearchIntaCode. Each row has the code, title, activity type (production/trade/services), vat_status (which VAT stage the activity falls in, or not subject), business group, profit_ratio (نسبت سود فعالیت, %) and gross_profit_to_sales_ratio (%), used for presumptive assessments. The ratios are not tax rates.
Inputs: query (required), year, limit, commercial.
Search the tax administration's official FAQ (پرسش های متداول) and return matching questions with links.
Source: tax.gov.ir SearchFAQ. Returns question titles and their page url; open the url for the answer.
Inputs: query (required).
Find e-invoice goods/service IDs (شناسه کالا و خدمات) and their VAT rate by description or ID.
Source: the tax administration's ID system stuffid.tax.gov.ir. Active general IDs come first. Each row has the
13-digit id, description, vat_percent, type (general/specific, domestic/imported) and dates; expired: true
means the ID can no longer be used. The first search for a phrase takes 15-30 s (the site builds a file);
repeats are cached for an hour. total counts every match, not only the rows returned.
Inputs: query (required), kind, limit, general_only.
Return the official property transaction value (ارزش معاملاتی املاک) per square metre at a map point.
Source: tax.gov.ir GetAddressGeoLocation. Gives the booklet block and row, residential/office/commercial values and rent values in rial per m² (text 'عدم وجود اطلاعات' when the booklet has none), and the tax offices for that address. The caller must supply coordinates; this server does not geocode addresses.
Inputs: latitude (required), longitude (required), year.
Search the official tax regulation database (laws, circulars, rulings, opinions), newest first.
Source: regulation.tax.gov.ir (سامانه جامع مقررات مالیاتی). Each item has id and type (pass both to tx_regulation_text), title, number, issuer, date (Jalali) and status (معتبر = in force, غیر معتبر = not).
Inputs: query (required), page, type, title_only.
Return the full text of one tax law, circular, ruling or opinion, or just one article of it.
Source: regulation.tax.gov.ir. Gives title, kind, number, dates, issuer, the official PDF link and the text in
reading order with each article heading on its own line. Long laws come in parts: parts > 1 means call again
with part=2, 3, ... For one article of a big law (the direct tax law is ~300 articles) pass article.
Inputs: id (required), type (required), part, article.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Each tool targets a clearly distinct resource: goods/service IDs, FAQ, regulations, regulation text, activity codes, and property values. The only near-pair (tx_regulations_search vs tx_regulation_text) is cleanly separated as a search/detail relationship, so an agent can reliably pick the right tool.
All names share a consistent tx_ prefix and snake_case, with a tx_<domain>_<action> scheme. Minor deviation is that some names encode an action (search/text) while others are pure nouns (activity_codes, property_value), but the set still reads predictably.
Six tools is well-scoped for a tax reference-data server. Each tool covers a distinct lookup category with no redundant or filler tools.
The surface covers the major tax reference domains (goods IDs, FAQ, regulations including full text, activity codes, property values) reasonably well. The main gap is that tx_property_value requires caller-supplied coordinates with no geocoding support, which a caller must work around.
Exact tools for agents: US tax, routing/EIN checks, business days, JSON, links, packages, citations.
Persian and Iranian utilities for agents: Jalali dates, national ID, IBAN, holidays. Paid via x402.
Irish Tax Hub helps users estimate Irish taxes, inspect current tax rates and deadlines, search Revenue guidance, and research Ireland's double-taxation treaties through read-only tools. Check out https://www.irishtaxhub.ie
Korean company facts in English for AI agents: ~830 KOSPI-listed companies (DART profiles, KRW financials, recent filings) and ~110,000 corporate public procurement suppliers (12-month KONEPS contract awards), plus live National Tax Service business status checks. 4 tools, keyless, read-only.
