qavanin-mcp
Advanced tools
Unofficial read-only MCP server for qavanin.ir: search Iranian laws and regulations, read their full text, amendments and status.
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
YYYY/MM/DD.uvx qavanin-mcp or claude mcp add qavanin -- uvx qavanin-mcp. Transport: stdio. Needs uv (Python 3.10+).QAVANIN_MCP_PROXY (HTTP proxy URL, or a comma-separated list tried in turn); system proxy settings are ignored.qv_. Typical sequence: qv_search -> qv_law (with article) -> qv_amendments -> qv_article_history.1405/07/22); document ids (id, the site's IDS) are 20-digit strings, keep them as strings; text uses Persian ی/ک.repealed or amended are not current text.server.json and the
iran-mcp catalog (TOOLS.md, servers.json, llms.txt).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_historyto show whether that article was changed.
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:
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.
| Tool | What it does |
|---|---|
qv_search | Search titles or full text, with filters for kind, approving body, executor, subject, type, status, dates and gazette numbers |
qv_lookup | Find the ids the search filters take: approving bodies, executing bodies, subjects, document types, statuses, curated lists |
qv_law | Read the text of a law as sections, one article with its notes, or the text as of a past date |
qv_law_info | Metadata: type, approver, approval, notification and gazette numbers and dates, last status, executors |
qv_amendments | Which laws amended this one, which it amends, and which of its articles were amended |
qv_article_history | Every amendment of one article: type, date, amending law, replacing text |
qv_related | Regulations, court votes and legal opinions related to a law |
All 7 tools are annotated readOnlyHint: true.
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.
1405/07/22), ids stay strings (20-digit), and text is normalised to Persian ی/ک. Placeholder dates such as 0000/00/00 are dropped.repealed or amended are not current text. Say which version and status you read.in_text it finds words inside the law text, so open candidates with qv_law(article=...).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.
uvx is not foundUse the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
| Variable | Default | Meaning |
|---|---|---|
QAVANIN_MCP_PROXY | unset | Optional HTTP proxy URL, or a comma-separated list tried in turn, for qavanin.ir; system proxies are ignored |
qavanin-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای سامانه ملی قوانین و مقررات جمهوری اسلامی ایران (qavanin.ir) است. دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) با آن می‌تواند در حدود ۱۶۸ هزار سند شامل قوانین، مقررات، آرای قضایی و نظرات حقوقی جستجو کند.
چه کارهایی می‌کند
نکته‌ها
1405/07/22) هستند و حروف عربی «ي» و «ك» در جستجو با «ی» و «ک» یکی حساب می‌شوند.کلیدواژه‌ها: قوانین و مقررات ایران، سامانه ملی قوانین و مقررات، قوانین کشور، متن قانون، قانون مدنی، آرای قضایی، نظرات مشورتی، اصلاحات قانون، سرور MCP قوانین.
نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add qavanin -- uvx qavanin-mcp
در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسش‌ها
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.
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.
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.
If this saves you time, a star helps others find it.
FAQs
Unofficial read-only MCP server for qavanin.ir: search Iranian laws and regulations, read their full text, amendments and status.
We found that qavanin-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.