Metadata-Version: 2.5
Name: qavanin-mcp
Version: 0.1.0
Summary: Unofficial read-only MCP server for qavanin.ir: search Iranian laws and regulations, read their full text, amendments and status.
Project-URL: Homepage, https://github.com/sepehr071/qavanin-mcp
Project-URL: Issues, https://github.com/sepehr071/qavanin-mcp/issues
Author-email: Sepehr Radmard <sepehrr80@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: iran,law,legal,mcp,model-context-protocol,qavanin,regulations
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: curl-cffi>=0.16.3
Requires-Dist: httpx-curl-cffi>=0.1.5
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.2
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.sepehr071/qavanin-mcp -->

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

**Unofficial, read-only MCP server for [qavanin.ir](https://qavanin.ir) (سامانه ملی قوانین و مقررات جمهوری اسلامی ایران), the national database of Iranian laws, regulations, court votes and legal opinions.**<br>
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.

[Quick start](#quick-start) · [For AI agents](#for-ai-agents) · [Tools](#tools) · [Notes](#notes) · [فارسی](#فارسی)

---

## For AI agents

- **What:** unofficial MCP server for qavanin.ir. Queries work in Persian (Arabic ي/ك and Persian ی/ک are equivalent); dates are Jalali `YYYY/MM/DD`.
- **Install:** `claude mcp add qavanin -- uvx qavanin-mcp` (stdio transport, needs [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+).
- **Auth:** none. Optional `QAVANIN_MCP_PROXY` sets an HTTP proxy for requests to qavanin.ir.
- **Access:** read-only. No login, subscription or purchase calls exist.
- **Tools:** 7, all prefixed `qv_`. Typical sequence: `qv_search` → `qv_law` (with `article`) → `qv_amendments` → `qv_article_history`.
- **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.
- **Output:** compact JSON. Document ids (`id`, the site's `IDS`) are 20-digit strings: keep them as strings. Output uses Persian letters. Sections marked `repealed` or `amended` are not current text.
- **Machine-readable:** [`server.json`](server.json), and the catalog of all Iranian MCP servers at [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp).

## Quick start

```bash
claude mcp add qavanin -- uvx qavanin-mcp
```

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

Example: «ماده ۱۰ قانون مدنی چه می‌گوید؟» → `qv_search(query="قانون مدنی", kind="law")` → `qv_law(ids=..., article="10")`.

## Tools

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

## Notes

- The site is slow: 1-15 s per call, the civil code about 15 s on first read (it is cached for 5 minutes, so paging through it is fast).
- The site sometimes ignores search filters and answers with the whole database; the server detects and retries that.
- Sorting by date has many ties, so paging a long list can repeat or skip a row: narrow the filters instead of paging deep.
- A bot-check cookie (ArvanCloud) is solved in Python; no browser is needed.

## فارسی

سرور MCP غیررسمی و فقط‌خواندنی برای سامانه ملی قوانین و مقررات (qavanin.ir): جستجو در عنوان یا متن حدود ۱۶۸ هزار سند، خواندن متن قانون یا یک ماده، تاریخچهٔ اصلاحات هر ماده و مقررات، آرا و نظرات مرتبط. نصب: `claude mcp add qavanin -- uvx qavanin-mcp`

## License

MIT. Not affiliated with qavanin.ir or the Iranian government.
