amar-mcp: Statistical Centre of Iran (مرکز آمار ایران) inflation, unemployment and census MCP server

amar-mcp is an unofficial, read-only MCP server that gives AI agents the official numbers of the Statistical Centre of Iran (amar.org.ir). Its 12 tools return the consumer price index and inflation (monthly, year-on-year, 12-month average, by CPI group, household region and province), unemployment and participation rates, GDP growth, producer prices, the monthly macro-indicators workbook (trade, housing price and rent, money, budget, household income and spending, CPI by decile), census population by province and county, news, the publishing calendar, and any Excel table of any release. No API key or account is needed. It works in Claude, Cursor, Copilot and any other MCP client.

For AI agents · Quick start · Tools · FAQ · فارسی

For AI agents

• What: unofficial MCP server (model context protocol) for amar.org.ir, Iran's national statistics portal: official CPI and inflation, labour force survey rates, census 1395 population, the release catalog and calendar, and a reader for the portal's Excel tables.

• Install: uvx amar-mcp or claude mcp add amar -- uvx amar-mcp. Transport: stdio. Needs uv (Python 3.10+).

• Auth: none. Optional AMAR_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.

• Access: read-only. It cannot log in or change anything, so no confirmation is needed before calling any tool.

• Network: amar.org.ir answers only from inside Iran (it drops foreign IPs), so run the server on an Iranian connection or set AMAR_MCP_PROXY to an Iranian proxy.

• Tools: 12, all prefixed am_. Typical sequences: am_inflation -> am_inflation_groups; am_gdp, am_ppi; am_indicators (topic -> table); am_search -> am_release -> am_table; am_calendar for "when is the next release".

• Use when: the user asks what Iran's official inflation, CPI, unemployment or population is, what drives inflation (food, housing...), how a province compares, when the Statistical Centre publishes something, or wants any table from amar.org.ir.

• Do not use when: the user wants central-bank data, exchange or gold prices (other servers cover those), or live market data. The monthly CPI Excel series trails the PDF report by about a week; am_inflation flags this in newer_report and reads the newer month's national figures from the PDF.

• Output: compact JSON. Periods are Jalali (1405-06 = Shahrivar 1405). Percentages are percent. Names and titles are Persian as the Centre has them.

• Machine-readable: server.json.

Related MCP server: iran-tax-mcp

Example

You: What is Iran's official inflation, and what drives it?

Agent: calls am_inflation() and am_inflation_groups()

For Shahrivar 1405 the Statistical Centre reports 4.24% monthly, 89.8% year-on-year and 73.6% for the 12-month average. Food and tobacco rose 122% year-on-year, transport 115%, housing 38%.

Numbers from a live call on 2026-11-01.

Other prompts: "unemployment rate by quarter", "population of Yazd province and its counties", "inflation in Fars province", "when is the next CPI release", تورم نقطه به نقطه مسکن شهری چقدر است؟, نرخ بیکاری آخرین فصل؟

Quick start

You need uv. No API key or account.

Claude Code: claude mcp add amar -- uvx amar-mcp

Claude Desktop, Cursor, Windsurf, Gemini CLI: add

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

VS Code: .vscode/mcp.json with {"servers": {"amar": {"type": "stdio", "command": "uvx", "args": ["amar-mcp"]}}}.

Codex CLI: codex mcp add amar -- uvx amar-mcp. Anything else: uvx amar-mcp, or pip install amar-mcp and run amar-mcp.

Tools

All 12 tools are annotated readOnlyHint: true.

How it works

  AI agent  ──MCP/stdio──▶  amar-mcp  ──HTTPS──▶  amar.org.ir  (release pages, Excel files)

The portal has no JSON API, so the server reads its catalog pages and downloads the Excel files that the portal itself offers, then parses them. It sends browser-like requests (Chrome TLS fingerprint), makes at most 3 concurrent requests, caches answers for 5 minutes and refuses files over 25 MB. The site's certificate chain is incomplete (it omits an intermediate); the server ships that public intermediate certificate to verify the connection normally.

FAQ

Why does it fail from outside Iran? amar.org.ir does not answer foreign IPs. Run it on an Iranian connection or set AMAR_MCP_PROXY.

Why is the newest month missing in am_inflation? The Centre publishes a PDF report first and updates the Excel series about a week later. The answer's newer_report names that release (use am_release for the PDF link); it also carries that month's national index and inflation, read from the PDF.

Are these the same as central-bank figures? No. These are the Statistical Centre's figures; the Central Bank of Iran publishes its own.

Is it affiliated with the Centre? No. It reads public pages and files, no login.

فارسی

amar-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای درگاه ملی آمار (مرکز آمار ایران، amar.org.ir) است. با آن می‌توانید تورم و شاخص قیمت مصرف‌کننده (ماهانه، نقطه‌به‌نقطه، متوسط ۱۲ ماه؛ به تفکیک گروه کالا، مناطق شهری و روستایی و استان)، نرخ بیکاری و مشارکت، جمعیت استان‌ها و شهرستان‌ها در سرشماری ۱۳۹۵، تقویم انتشار و هر جدول اکسل منتشرشده را بپرسید.

نصب: claude mcp add amar -- uvx amar-mcp (نیاز به uv). درگاه مرکز آمار فقط از داخل ایران پاسخ می‌دهد؛ سرور را روی اینترنت ایران اجرا کنید یا AMAR_MCP_PROXY را روی یک پروکسی ایرانی بگذارید.

Author: Sepehr Radmard (سپهر رادمرد), github.com/sepehr071, linkedin.com/in/sepehr-radmard. MIT license.