Qavanin

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 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 Code

claude mcp add qavanin -- uvx qavanin-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

{

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

</details>

Cursor

Add the Claude Desktop block to ~/.cursor/mcp.json.

VS Code (Copilot agent mode)

Click Install in VS Code above, or add to .vscode/mcp.json:

{

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

</details>

Codex CLI

codex mcp add qavanin -- uvx qavanin-mcp

Or in ~/.codex/config.toml:

[mcp_servers.qavanin]

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

</details>

Gemini CLI

Add to ~/.gemini/settings.json:

{

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

</details>

Windsurf

Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.

Anything else

It's a standard stdio MCP server: run uvx qavanin-mcp, or pip install qavanin-mcp and run 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

Is there an MCP server or API for Iranian laws (qavanin.ir)?

Yes: qavanin-mcp is an unofficial MCP server with 7 read-only tools for searching and reading laws, regulations, court votes and legal opinions on qavanin.ir. It reads the same pages as the website; no API key is needed.

How do I use it with Claude, Cursor or Copilot?

Add the server with claude mcp add qavanin -- uvx qavanin-mcp (or the matching config in Quick start), then ask in plain language, in Persian or English.

Is it official, safe and free?

It is unofficial and not affiliated with qavanin.ir or the Iranian government. It is read-only, runs on your machine, and is free under the MIT license.

Is the text legally binding or up to date?

No. It shows what the site shows. Check each document's status and amendments (qv_law_info, qv_amendments) before relying on it, and consult a lawyer for legal advice.

Can I search with Arabic letters (ي/ك)?

Yes. The site stores Arabic ي/ك, and queries in either form match. Output is normalised to Persian ی/ک.

Why is it slow on the first read of a big law?

The site returns a whole law in one response (the civil code is about 892 KB). The server caches it for 5 minutes, so reading further articles is fast.

Can it log in, comment or subscribe?

No. It has no login and never calls comment, subscription or purchase endpoints.

I get a bot-check or connection error

The server solves qavanin.ir's cookie challenge itself. If your network still cannot reach the site, set QAVANIN_MCP_PROXY to an HTTP proxy that can. System proxy variables are ignored on purpose.

Claude Desktop says uvx is not found

Use the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as `