qavanin-mcp: Iranian laws and regulations MCP server for AI agents

Let your AI agent read Iranian law (قوانین و مقررات ایران).
An unofficial, read-only MCP server for qavanin.ir (سامانه ملی قوانین و مقررات جمهوری اسلامی ایران), the national database of Iranian laws, regulations, court votes and legal opinions.
Search about 168,000 documents by title or full text, read a law or a single article, see how an article was amended, and follow the regulations and court votes that cite it, all from Claude, Cursor or Copilot.

For AI agents · Why · What it can do · Quick start · Tools · How it works · Good to know · FAQ · Configuration · فارسی · Development · Related · Disclaimer · License

For AI agents

• What: unofficial MCP server (model context protocol) for qavanin.ir, Iran's national laws and regulations database. Queries work in Persian (Arabic ي/ك and Persian ی/ک are equivalent); dates are Jalali YYYY/MM/DD.
• Install: uvx qavanin-mcp or claude mcp add qavanin -- uvx qavanin-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account. Optional QAVANIN_MCP_PROXY (HTTP proxy URL, or a comma-separated list tried in turn); system proxy settings are ignored.
• Access: read-only. No login, subscription or purchase calls exist, so no confirmation is needed before calling any tool.
• Tools: 7, all prefixed qv_. Typical sequence: qv_search -> qv_law (with article) -> qv_amendments -> qv_article_history.
• Units: dates are Jalali strings (1405/07/22); document ids (id, the site's IDS) are 20-digit strings, keep them as strings; text uses Persian ی/ک.
• Use when: looking up what an Iranian law, regulation, court ruling or legal opinion says, when it was approved and published, whether it was amended or repealed, and what cites it.
• Do not use when: the user needs legal advice or a binding interpretation. The site is a reference database; always say which version and status you read. Sections marked repealed or amended are not current text.
• Machine-readable: server.json and the awesome-iran-mcp catalog (TOOLS.md, servers.json, llms.txt).

Why

Iranian legislation is spread over thousands of laws, by-laws, court votes and opinions, and a law's current text depends on later amendments. Answering "what does article 10 of the civil code say, was it ever amended, and which regulations cite it?" means a lot of searching on a slow, server-rendered site. With qavanin-mcp an agent does it in a few calls and returns only the relevant article instead of an 892 KB law.

You: ماده ۱۰ قانون مدنی چه می‌گوید؟

Agent: calls qv_search(query="قانون مدنی", kind="law") -> qv_law(ids=..., article="10")

It finds the civil code, reads just article 10 with its notes, and can follow up with qv_article_history to show whether that article was changed.

What it can do

• Search about 168,000 laws, regulations, court votes and legal opinions by title or full text, with filters for kind, approving body, executor, subject, document type, status, dates and gazette numbers
• Read a law as sections, a single article with its notes, or the text as of a past date
• Check status: approval, notification and gazette numbers and dates, last status, executors
• Trace amendments: which laws amended this one, which it amends, and every amendment of one article with its replacing text
• Follow citations: regulations, court votes and legal opinions related to a law
• Look up filter ids: approving bodies, executing bodies, subjects, document types, statuses and curated lists
• Read-only by design: no login, no comments, no subscriptions, no purchases

Quick start

You need uv. No API key or account.

claude mcp add qavanin -- uvx qavanin-mcp

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

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

codex mcp add qavanin -- uvx qavanin-mcp

[mcp_servers.qavanin]
command = "uvx"
args = ["qavanin-mcp"]

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

Then just ask:

• "What does article 10 of the Iranian civil code say?"
• "Was article 1 of this law ever amended? Show the amendment history."
• "Find the latest laws approved by the Majlis and list their gazette numbers."
• "Which regulations and court votes are related to the Iranian Commercial Code?"
• "Show the text of this law as it was on 1400/01/01."
• ماده ۱۰ قانون مدنی چه می‌گوید؟
• آیا ماده ۱ این قانون اصلاح شده است؟ تاریخچه اصلاحات را نشان بده.
• آیین‌نامه‌ها و آرای مرتبط با قانون تجارت کدام‌اند؟

Tools

All tools return compact JSON. Document ids from qv_search go to the other tools; qv_lookup finds the ids that qv_search filters take.

All 7 tools are annotated readOnlyHint: true.

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  qavanin-mcp  (runs on your machine)
      │
      │  HTTPS
      └──────▶  qavanin.ir   laws, regulations, court votes, opinions

qavanin-mcp runs locally and reads the same pages the qavanin.ir website serves (server-rendered HTML plus two small JSON lookups). There is no hosted server in between and no API key. The site's bot-check cookie is solved in Python, so no browser is needed.

Good to know

• The site is slow: 1-15 s per call. The civil code takes about 15 s on first read; it is cached for 5 minutes, so paging through it is fast.
• Dates are Jalali (1405/07/22), ids stay strings (20-digit), and text is normalised to Persian ی/ک. Placeholder dates such as 0000/00/00 are dropped.
• Status matters: sections marked repealed or amended are not current text. Say which version and status you read.
• Full-text search shows no snippet. With in_text it finds words inside the law text, so open candidates with qv_law(article=...).
• The site sometimes ignores search filters and answers with the whole database; the server detects that and retries.
• Sorting by date has ties, so paging a long list can repeat or skip a row: narrow the filters instead of paging deep.
• Not covered: comments, subscriptions, purchases and any account feature. It is a research aid, not legal advice.

FAQ

Configuration

فارسی

claude mcp add qavanin -- uvx qavanin-mcp

Development

git clone https://github.com/sepehr071/qavanin-mcp && cd qavanin-mcp
uv sync
uv run python -m pytest            # offline, against recorded responses
uv run python -m pytest -m live    # real site, slow
uv run ruff check .

Tools live in src/qavanin_mcp/search.py and law.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 tests, publishes to PyPI and the MCP Registry, and creates the GitHub Release.

Related servers

• Iran Tax MCP server for Iranian tax and Codal data
• Paziresh24 MCP server for doctors and appointments
• Iran News MCP server for Iranian news
• Iran Apps MCP server for Iranian apps
• awesome-iran-mcp: catalog of all Iranian-service MCP servers

Disclaimer

Unofficial and not affiliated with or endorsed by qavanin.ir or the Iranian government. It reads the pages of the qavanin.ir website, which can change without notice, and it is a research aid, not legal advice. Please keep request rates reasonable.

License

MIT

If this saves you time, a star helps others find it.