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).

Related MCP server: Legalize

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

Settings → Developer → Edit Config, then add:

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

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

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

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

codex mcp add qavanin -- uvx qavanin-mcp

Or in ~/.codex/config.toml:

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

Add to ~/.gemini/settings.json:

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

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

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

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.

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.

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.

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.

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

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.

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

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.

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

Configuration

فارسی

سرور MCP قوانین و مقررات ایران برای دستیار هوش مصنوعی

qavanin-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای سامانه ملی قوانین و مقررات جمهوری اسلامی ایران (qavanin.ir) است. دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) با آن می‌تواند در حدود ۱۶۸ هزار سند شامل قوانین، مقررات، آرای قضایی و نظرات حقوقی جستجو کند.

چه کارهایی می‌کند

• جستجو در عنوان یا متن اسناد، با فیلتر نوع سند، مرجع تصویب‌کننده، دستگاه اجرایی، موضوع، وضعیت، تاریخ و شماره روزنامه رسمی.

• خواندن متن قانون، یک ماده با تبصره‌هایش، یا متن قانون در یک تاریخ گذشته.

• اطلاعات سند: تاریخ تصویب و ابلاغ، شماره روزنامه رسمی، آخرین وضعیت و دستگاه‌های اجرایی.

• اصلاحات: کدام قوانین این قانون را اصلاح کرده‌اند و تاریخچهٔ اصلاح هر ماده.

• مقررات و آرای مرتبط: آیین‌نامه‌ها، آرای دادگاه‌ها و نظرات مرتبط با هر قانون.

نکته‌ها

• فقط خواندنی است: وارد حساب نمی‌شود، اشتراک یا خرید ندارد.

• تاریخ‌ها شمسی (مثل 1405/07/22) هستند و حروف عربی «ي» و «ك» در جستجو با «ی» و «ک» یکی حساب می‌شوند.

• سایت کند است (۱ تا ۱۵ ثانیه برای هر درخواست). این ابزار مشاوره حقوقی نیست؛ وضعیت و اصلاحات هر متن را بررسی کنید.

• روی سیستم خود شما اجرا می‌شود و کلید API لازم ندارد.

کلیدواژه‌ها: قوانین و مقررات ایران، سامانه ملی قوانین و مقررات، قوانین کشور، متن قانون، قانون مدنی، آرای قضایی، نظرات مشورتی، اصلاحات قانون، سرور MCP قوانین.

نصب (اول uv را نصب کنید). در Claude Code:

claude mcp add qavanin -- uvx qavanin-mcp

در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.

نمونه پرسش‌ها

• «ماده ۱۰ قانون مدنی چه می‌گوید؟»

• «آیا ماده ۱ این قانون اصلاح شده است؟»

• «آیین‌نامه‌های مرتبط با قانون تجارت را فهرست کن.»

• «متن این قانون در تاریخ ۱۴۰۰/۰۱/۰۱ چه بود؟»

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

• iran-mcp: catalog of all Iranian-service MCP servers

• Listed on mcpfarsi.ir, the Persian MCP marketplace

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.

Author

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.

License

MIT

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