iran-tax-mcp: Iranian tax services 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 · Quick start · Tools · FAQ · فارسی
For AI agents
- What: unofficial MCP server for public services of the Iranian National Tax Administration (سازمان امور مالیاتی کشور): tax.gov.ir, stuffid.tax.gov.ir and regulation.tax.gov.ir. Persian text.
- Install:
uvx iran-tax-mcporclaude mcp add iran-tax -- uvx iran-tax-mcp. Transport: stdio. Needs uv (Python 3.10+). - Auth: none. 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:
tx_goods_search,tx_activity_codes,tx_property_value,tx_regulations_search,tx_regulation_text,tx_faq_search. - 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. - Machine-readable:
server.jsonand the awesome-iran-mcp catalog.
Quick start
claude mcp add iran-tax -- uvx iran-tax-mcp
Other clients: command uvx, args ["iran-tax-mcp"].
Tools
| Tool | What it does |
|---|---|
tx_goods_search |
E-invoice goods/service IDs (شناسه کالا و خدمات) with VAT rate, type and validity, by description or 13-digit ID (query, kind, general_only, limit 1-20). First search for a phrase takes 15-30 s; cached for an hour. |
tx_activity_codes |
Activity codes (اینتاکد) with VAT stage, business group and official profit ratios (query, year, commercial, limit 1-20). |
tx_property_value |
Official property transaction value (ارزش معاملاتی) and rent value per m², booklet block and row, and the tax offices for a point (latitude, longitude, year). |
tx_regulations_search |
Search tax laws, regulations and circulars, rulings, opinions, correspondence and glossary, newest first (query, type, title_only, page). |
tx_regulation_text |
Full text of one document, or one article of it such as ماده 169 مکرر, with metadata and the official PDF link (id, type, article, part). |
tx_faq_search |
The tax administration's FAQ: matching questions with links (query). |
FAQ
Does it work outside Iran? 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.
Why no economic-code (شماره اقتصادی) or invalid-company lookup? 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.
Why is the first goods search slow? The ID system answers a search by building a file (15-30 s for a broad phrase such as «لپ تاپ», tens of thousands of rows). The server downloads it once, ranks it (active general IDs first) and keeps it for an hour.
فارسی
سرور MCP غیررسمی و فقط‌خواندنی برای خدمات عمومی سازمان امور مالیاتی کشور: جست‌وجوی شناسه کالا و خدمات (صورتحساب الکترونیکی) و نرخ ارزش افزوده، کد فعالیت (اینتاکد)، ارزش معاملاتی املاک، متن قوانین، بخشنامه‌ها و آرای مالیاتی از سامانه جامع مقررات مالیاتی، و پرسش‌های متداول.
claude mcp add iran-tax -- uvx iran-tax-mcp
1 maintainer
Metadata
1 maintainer
Release files for iran-tax-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| iran_tax_mcp-0.1.0.tar.gz | 125.8 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| iran_tax_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 147.9 kB
Release files / iran_tax_mcp-0.1.0.tar.gz
| Download URL | iran_tax_mcp-0.1.0.tar.gz |
|---|---|
| Size | 125.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fd01367e47acd5f87b1bc1b6e4048211c2059c3b84c38a22f372460615d1713f
|
|
BLAKE2b-256 checksum How to use checksums |
ada632547778ce687662e8b46a777c244f95a7ebe29d06e4280dd66cc49e6ff4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logRelease files / iran_tax_mcp-0.1.0-py3-none-any.whl
| Download URL | iran_tax_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 22.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5020f3e2b28df6374a55acaf5575412f8aa72cb8a37676b0eae92d31275f6aaa
|
|
BLAKE2b-256 checksum How to use checksums |
942565e5f2bba6ca95ce8fa2e2bfc44e5deb12f4dfaf31f0305b33017296c172
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logSecurity for iran-tax-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for iran_tax_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
