cbi-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cbi_mcp-0.1.0/.github/workflows/ci.yml +22 -0
- cbi_mcp-0.1.0/.github/workflows/publish.yml +51 -0
- cbi_mcp-0.1.0/.gitignore +6 -0
- cbi_mcp-0.1.0/LICENSE +21 -0
- cbi_mcp-0.1.0/PKG-INFO +140 -0
- cbi_mcp-0.1.0/README.md +110 -0
- cbi_mcp-0.1.0/pyproject.toml +58 -0
- cbi_mcp-0.1.0/server.json +32 -0
- cbi_mcp-0.1.0/src/cbi_mcp/__init__.py +5 -0
- cbi_mcp-0.1.0/src/cbi_mcp/bank.py +512 -0
- cbi_mcp-0.1.0/src/cbi_mcp/http.py +245 -0
- cbi_mcp-0.1.0/src/cbi_mcp/registry.py +16 -0
- cbi_mcp-0.1.0/src/cbi_mcp/server.py +95 -0
- cbi_mcp-0.1.0/src/cbi_mcp/stats.py +374 -0
- cbi_mcp-0.1.0/tests/conftest.py +69 -0
- cbi_mcp-0.1.0/tests/fixtures/annual.html +776 -0
- cbi_mcp-0.1.0/tests/fixtures/auction_item.html +6 -0
- cbi_mcp-0.1.0/tests/fixtures/bop.xlsx +0 -0
- cbi_mcp-0.1.0/tests/fixtures/inflation.html +2431 -0
- cbi_mcp-0.1.0/tests/fixtures/monetary.html +339 -0
- cbi_mcp-0.1.0/tests/fixtures/monetary_item.html +146 -0
- cbi_mcp-0.1.0/tests/fixtures/news_home.html +513 -0
- cbi_mcp-0.1.0/tests/fixtures/news_item.html +104 -0
- cbi_mcp-0.1.0/tests/fixtures/news_list.html +446 -0
- cbi_mcp-0.1.0/tests/fixtures/omo.pdf +0 -0
- cbi_mcp-0.1.0/tests/fixtures/omo_list.html +37 -0
- cbi_mcp-0.1.0/tests/fixtures/policy.html +1209 -0
- cbi_mcp-0.1.0/tests/fixtures/rates.html +2416 -0
- cbi_mcp-0.1.0/tests/fixtures/rss_usd.xml +74 -0
- cbi_mcp-0.1.0/tests/fixtures/stats_category.html +42 -0
- cbi_mcp-0.1.0/tests/fixtures/stats_month.html +24 -0
- cbi_mcp-0.1.0/tests/fixtures/trends.html +237 -0
- cbi_mcp-0.1.0/tests/fixtures/trends_item.html +132 -0
- cbi_mcp-0.1.0/tests/test_cbi.py +301 -0
- cbi_mcp-0.1.0/tests/test_live_cbi.py +85 -0
- cbi_mcp-0.1.0/uv.lock +1387 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ["3.10", "3.11", "3.12", "3.13"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v7
|
|
16
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
- run: uv sync --locked
|
|
20
|
+
- run: uv run ruff check .
|
|
21
|
+
- run: uv run ruff format --check .
|
|
22
|
+
- run: uv run pytest -q
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
name: Publish
|
|
2
|
+
|
|
3
|
+
# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
|
|
4
|
+
# pyproject.toml and server.json.
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
tags: ["v*"]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
pypi:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
environment: pypi
|
|
13
|
+
permissions:
|
|
14
|
+
id-token: write # PyPI trusted publishing
|
|
15
|
+
contents: write # GitHub Release
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v7
|
|
18
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
19
|
+
- name: Check versions match the tag
|
|
20
|
+
run: |
|
|
21
|
+
TAG=${GITHUB_REF_NAME#v}
|
|
22
|
+
grep -q "^version = \"$TAG\"" pyproject.toml
|
|
23
|
+
test "$(jq -r .version server.json)" = "$TAG"
|
|
24
|
+
test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
|
|
25
|
+
- run: uv sync --locked && uv run pytest -q
|
|
26
|
+
- run: uv build
|
|
27
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
28
|
+
- run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
|
|
29
|
+
env:
|
|
30
|
+
GH_TOKEN: ${{ github.token }}
|
|
31
|
+
|
|
32
|
+
mcp-registry:
|
|
33
|
+
needs: pypi
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
permissions:
|
|
36
|
+
id-token: write # MCP Registry login via GitHub OIDC
|
|
37
|
+
contents: read
|
|
38
|
+
steps:
|
|
39
|
+
- uses: actions/checkout@v7
|
|
40
|
+
- name: Wait for PyPI to serve the new version
|
|
41
|
+
run: |
|
|
42
|
+
for i in $(seq 1 30); do
|
|
43
|
+
curl -sf "https://pypi.org/pypi/cbi-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
|
|
44
|
+
sleep 10
|
|
45
|
+
done
|
|
46
|
+
exit 1
|
|
47
|
+
- name: Install mcp-publisher
|
|
48
|
+
run: |
|
|
49
|
+
curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
|
|
50
|
+
- run: ./mcp-publisher login github-oidc
|
|
51
|
+
- run: ./mcp-publisher publish
|
cbi_mcp-0.1.0/.gitignore
ADDED
cbi_mcp-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sepehr Radmard
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
cbi_mcp-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: cbi-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial read-only MCP server for the Central Bank of Iran (cbi.ir): official exchange rates, inflation, policy rates, news.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sepehr071/cbi-mcp
|
|
6
|
+
Project-URL: Issues, https://github.com/sepehr071/cbi-mcp/issues
|
|
7
|
+
Project-URL: Website, https://mcpfarsi.ir/
|
|
8
|
+
Author-email: Sepehr Radmard <sepehrr80@gmail.com>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: cbi,cbi-ir,central-bank-of-iran,claude,exchange-rate,inflation,interest-rate,iran,liquidity,mcp,model-context-protocol,persian,rial
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: curl-cffi>=0.16.3
|
|
24
|
+
Requires-Dist: httpx-curl-cffi>=0.1.5
|
|
25
|
+
Requires-Dist: httpx>=0.27
|
|
26
|
+
Requires-Dist: mcp<3,>=2.2
|
|
27
|
+
Requires-Dist: pypdf>=5
|
|
28
|
+
Requires-Dist: xlrd>=2.0.1
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
<!-- mcp-name: io.github.sepehr071/cbi-mcp -->
|
|
32
|
+
|
|
33
|
+
<div align="center">
|
|
34
|
+
|
|
35
|
+
# cbi-mcp: Central Bank of Iran (بانک مرکزی) exchange rates, inflation and policy rates MCP server for AI agents
|
|
36
|
+
|
|
37
|
+
**cbi-mcp is an unofficial, read-only MCP server that gives AI agents the public data of the Central Bank of Iran (cbi.ir).**<br>
|
|
38
|
+
Its 8 tools read the official reference exchange rates and their history, inflation, the weekly interbank and policy rates,<br>
|
|
39
|
+
the bank's news and liquidity (نقدینگی) statements, and list its reports with download links.<br>
|
|
40
|
+
No API key or account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
|
|
41
|
+
|
|
42
|
+
[](https://pypi.org/project/cbi-mcp/)
|
|
43
|
+
[](https://pypi.org/project/cbi-mcp/)
|
|
44
|
+
[](https://github.com/sepehr071/cbi-mcp/blob/main/LICENSE)
|
|
45
|
+
|
|
46
|
+
[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
|
|
47
|
+
|
|
48
|
+
</div>
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## For AI agents
|
|
53
|
+
|
|
54
|
+
- **What:** unofficial MCP server (model context protocol) for cbi.ir: official exchange rates (about 48 currencies, archive back to 1383), inflation by month and year, weekly interbank/standing-facility rates, news and announcements, liquidity statements, reports (Economic Trends, monthly monetary statistics, annual review).
|
|
55
|
+
- **Install:** `uvx cbi-mcp` or `claude mcp add cbi -- uvx cbi-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
|
|
56
|
+
- **Auth:** none. Optional `CBI_MCP_PROXY` (HTTP proxy URL); system proxy settings are ignored.
|
|
57
|
+
- **Access:** read-only, no confirmation needed before calling any tool.
|
|
58
|
+
- **Tools:** 11, all prefixed `cb_`. Typical sequences: `cb_exchange_rates`; `cb_rate_history`; `cb_inflation`; `cb_news` -> `cb_news_item`; `cb_liquidity`; `cb_statistics`; `cb_bond_auctions`; `cb_policy_rates` + `cb_open_market`.
|
|
59
|
+
- **Use when:** the user asks for the official dollar/euro/dirham rate on a day, how a rate moved, Iran's inflation, interest or interbank rates, liquidity growth, or what the central bank announced.
|
|
60
|
+
- **Do not use when:** the user wants the free-market (bazaar) rate, which the CBI does not publish, or a series from the CBI time-series database (tsd.cbi.ir did not answer when this was built).
|
|
61
|
+
- **Output:** compact JSON. Rates are rials per currency unit (`per_units`: JPY 100, KRW 1000...). Dates in answers are Jalali; arguments accept Jalali (1404/01/01) or Gregorian (2025-03-21). Text is Persian.
|
|
62
|
+
- **Machine-readable:** [`server.json`](https://github.com/sepehr071/cbi-mcp/blob/main/server.json).
|
|
63
|
+
|
|
64
|
+
## Why
|
|
65
|
+
|
|
66
|
+
The Central Bank's site is a classic ASP.NET website: no API, one rate table per date, inflation behind a year dropdown,
|
|
67
|
+
liquidity buried in news and Excel files. `cbi-mcp` reads those pages for the agent:
|
|
68
|
+
|
|
69
|
+
> **You:** What was the official dollar rate on 1 Farvardin 1404, and what is it now?
|
|
70
|
+
>
|
|
71
|
+
> **Agent:** *calls* `cb_exchange_rates(date="1404/01/01", currencies=["USD"])` and `cb_exchange_rates(currencies=["USD"])`
|
|
72
|
+
>
|
|
73
|
+
> 579,503 rials on 1404/01/01 and 1,871,664 rials on 1405/08/09.
|
|
74
|
+
|
|
75
|
+
<sub>Real values read from cbi.ir on 2026-10-31.</sub>
|
|
76
|
+
|
|
77
|
+
## What it can do
|
|
78
|
+
|
|
79
|
+
- **Official exchange rates** for a day, today or from the archive, all currencies or a chosen few
|
|
80
|
+
- **Rate history** of one currency: last 7 days in one call, or a sampled series over months or years with total change
|
|
81
|
+
- **Inflation**: the 12-month rate for each month of any year since 1361 plus annual inflation back to 1316
|
|
82
|
+
- **Policy rates**: weekly interbank rate, minimum repo rate and the standing lending/deposit corridor
|
|
83
|
+
- **News** titles, filterable by a word, and the full text of any item
|
|
84
|
+
- **Liquidity** as numbers (liquidity, money, quasi-money, monetary base with yearly growth) from the newest monthly Excel, plus the governor's latest statements
|
|
85
|
+
- **Monthly statistics tables** read from the Excel files: monetary, balance of payments (foreign debt, monthly average dollar in the official, free and preferential markets), fiscal, capital market
|
|
86
|
+
- **Government sukuk auctions**: offered, sold and yield per bond, every week
|
|
87
|
+
- **Open market operations**: the weekly repo auction figures
|
|
88
|
+
- **Publications** with PDF/Excel links: Economic Trends, monthly monetary statistics, annual economic review, interbank market review
|
|
89
|
+
|
|
90
|
+
Example prompts:
|
|
91
|
+
|
|
92
|
+
- "What is the CBI's official euro rate today, and how much did it change over the last week?"
|
|
93
|
+
- "Show the dollar rate every month since Farvardin 1404."
|
|
94
|
+
- "What is Iran's inflation now and how did it move in 1403?"
|
|
95
|
+
- "What did the central bank say about liquidity growth recently?"
|
|
96
|
+
- <span dir="rtl">نرخ رسمی دلار بانک مرکزی امروز چقدر است؟</span>
|
|
97
|
+
- <span dir="rtl">آخرین گزارش نماگرهای اقتصادی را بده.</span>
|
|
98
|
+
|
|
99
|
+
## Quick start
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
claude mcp add cbi -- uvx cbi-mcp
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Any client: command `uvx`, args `["cbi-mcp"]`. Behind a proxy set `CBI_MCP_PROXY=http://host:port`.
|
|
106
|
+
|
|
107
|
+
## Tools
|
|
108
|
+
|
|
109
|
+
| Tool | What it returns |
|
|
110
|
+
|---|---|
|
|
111
|
+
| `cb_exchange_rates` | Official rates of ~48 currencies for a date (default latest), optional currency filter |
|
|
112
|
+
| `cb_rate_history` | One currency over time with change %; last 7 days, or sampled between two dates |
|
|
113
|
+
| `cb_inflation` | Monthly 12-month inflation for a Jalali year and annual inflation history |
|
|
114
|
+
| `cb_policy_rates` | Weekly interbank, repo and standing-facility rates for a year |
|
|
115
|
+
| `cb_news` | News titles (id, date), optional word filter and year |
|
|
116
|
+
| `cb_news_item` | Full text and attachments of one news item |
|
|
117
|
+
| `cb_liquidity` | Liquidity, money, quasi-money and monetary base (balance, yearly growth) from the newest monthly Excel, plus latest statements |
|
|
118
|
+
| `cb_publications` | Newest Economic Trends, monthly monetary reports, annual or interbank reviews with file links |
|
|
119
|
+
| `cb_statistics` | Rows of any sheet of the monthly Excel tables: monetary, balance_of_payments, fiscal, capital_market (year, month, sheet) |
|
|
120
|
+
| `cb_bond_auctions` | Results of the newest weekly government sukuk auctions per bond: offered, sold, yield |
|
|
121
|
+
| `cb_open_market` | Weekly open market operation reports with the newest repo auction figures |
|
|
122
|
+
|
|
123
|
+
## FAQ
|
|
124
|
+
|
|
125
|
+
**Is this the market rate?** No. These are the CBI's official reference rates; the free-market rate is not published there.
|
|
126
|
+
|
|
127
|
+
**Why no time-series search?** The bank's series database (tsd.cbi.ir) did not answer from any network tried.
|
|
128
|
+
|
|
129
|
+
**Does it read the Excel/PDF reports?** The monthly Excel statistics tables (`cb_statistics`, `cb_liquidity`), the weekly repo report and the auction results are read as numbers. Other Excel and PDF reports come back as links.
|
|
130
|
+
|
|
131
|
+
## License
|
|
132
|
+
|
|
133
|
+
MIT. Unofficial; not affiliated with the Central Bank of the Islamic Republic of Iran. Data belongs to its publisher.
|
|
134
|
+
|
|
135
|
+
Built by Sepehr Radmard (سپهر رادمرد): github.com/sepehr071 · linkedin.com/in/sepehr-radmard
|
|
136
|
+
|
|
137
|
+
## فارسی
|
|
138
|
+
|
|
139
|
+
`cbi-mcp` یک سرور MCP غیررسمی و فقطخواندنی برای سایت بانک مرکزی جمهوری اسلامی ایران (cbi.ir) است: نرخ رسمی ارز و تاریخچه آن، نرخ تورم، نرخهای سود بازار بینبانکی، اخبار و اظهارات نقدینگی و فهرست گزارشها با پیوند دانلود. نیازی به کلید یا حساب نیست.
|
|
140
|
+
نصب: `claude mcp add cbi -- uvx cbi-mcp`
|
cbi_mcp-0.1.0/README.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
<!-- mcp-name: io.github.sepehr071/cbi-mcp -->
|
|
2
|
+
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
# cbi-mcp: Central Bank of Iran (بانک مرکزی) exchange rates, inflation and policy rates MCP server for AI agents
|
|
6
|
+
|
|
7
|
+
**cbi-mcp is an unofficial, read-only MCP server that gives AI agents the public data of the Central Bank of Iran (cbi.ir).**<br>
|
|
8
|
+
Its 8 tools read the official reference exchange rates and their history, inflation, the weekly interbank and policy rates,<br>
|
|
9
|
+
the bank's news and liquidity (نقدینگی) statements, and list its reports with download links.<br>
|
|
10
|
+
No API key or account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
|
|
11
|
+
|
|
12
|
+
[](https://pypi.org/project/cbi-mcp/)
|
|
13
|
+
[](https://pypi.org/project/cbi-mcp/)
|
|
14
|
+
[](https://github.com/sepehr071/cbi-mcp/blob/main/LICENSE)
|
|
15
|
+
|
|
16
|
+
[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
|
|
17
|
+
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## For AI agents
|
|
23
|
+
|
|
24
|
+
- **What:** unofficial MCP server (model context protocol) for cbi.ir: official exchange rates (about 48 currencies, archive back to 1383), inflation by month and year, weekly interbank/standing-facility rates, news and announcements, liquidity statements, reports (Economic Trends, monthly monetary statistics, annual review).
|
|
25
|
+
- **Install:** `uvx cbi-mcp` or `claude mcp add cbi -- uvx cbi-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
|
|
26
|
+
- **Auth:** none. Optional `CBI_MCP_PROXY` (HTTP proxy URL); system proxy settings are ignored.
|
|
27
|
+
- **Access:** read-only, no confirmation needed before calling any tool.
|
|
28
|
+
- **Tools:** 11, all prefixed `cb_`. Typical sequences: `cb_exchange_rates`; `cb_rate_history`; `cb_inflation`; `cb_news` -> `cb_news_item`; `cb_liquidity`; `cb_statistics`; `cb_bond_auctions`; `cb_policy_rates` + `cb_open_market`.
|
|
29
|
+
- **Use when:** the user asks for the official dollar/euro/dirham rate on a day, how a rate moved, Iran's inflation, interest or interbank rates, liquidity growth, or what the central bank announced.
|
|
30
|
+
- **Do not use when:** the user wants the free-market (bazaar) rate, which the CBI does not publish, or a series from the CBI time-series database (tsd.cbi.ir did not answer when this was built).
|
|
31
|
+
- **Output:** compact JSON. Rates are rials per currency unit (`per_units`: JPY 100, KRW 1000...). Dates in answers are Jalali; arguments accept Jalali (1404/01/01) or Gregorian (2025-03-21). Text is Persian.
|
|
32
|
+
- **Machine-readable:** [`server.json`](https://github.com/sepehr071/cbi-mcp/blob/main/server.json).
|
|
33
|
+
|
|
34
|
+
## Why
|
|
35
|
+
|
|
36
|
+
The Central Bank's site is a classic ASP.NET website: no API, one rate table per date, inflation behind a year dropdown,
|
|
37
|
+
liquidity buried in news and Excel files. `cbi-mcp` reads those pages for the agent:
|
|
38
|
+
|
|
39
|
+
> **You:** What was the official dollar rate on 1 Farvardin 1404, and what is it now?
|
|
40
|
+
>
|
|
41
|
+
> **Agent:** *calls* `cb_exchange_rates(date="1404/01/01", currencies=["USD"])` and `cb_exchange_rates(currencies=["USD"])`
|
|
42
|
+
>
|
|
43
|
+
> 579,503 rials on 1404/01/01 and 1,871,664 rials on 1405/08/09.
|
|
44
|
+
|
|
45
|
+
<sub>Real values read from cbi.ir on 2026-10-31.</sub>
|
|
46
|
+
|
|
47
|
+
## What it can do
|
|
48
|
+
|
|
49
|
+
- **Official exchange rates** for a day, today or from the archive, all currencies or a chosen few
|
|
50
|
+
- **Rate history** of one currency: last 7 days in one call, or a sampled series over months or years with total change
|
|
51
|
+
- **Inflation**: the 12-month rate for each month of any year since 1361 plus annual inflation back to 1316
|
|
52
|
+
- **Policy rates**: weekly interbank rate, minimum repo rate and the standing lending/deposit corridor
|
|
53
|
+
- **News** titles, filterable by a word, and the full text of any item
|
|
54
|
+
- **Liquidity** as numbers (liquidity, money, quasi-money, monetary base with yearly growth) from the newest monthly Excel, plus the governor's latest statements
|
|
55
|
+
- **Monthly statistics tables** read from the Excel files: monetary, balance of payments (foreign debt, monthly average dollar in the official, free and preferential markets), fiscal, capital market
|
|
56
|
+
- **Government sukuk auctions**: offered, sold and yield per bond, every week
|
|
57
|
+
- **Open market operations**: the weekly repo auction figures
|
|
58
|
+
- **Publications** with PDF/Excel links: Economic Trends, monthly monetary statistics, annual economic review, interbank market review
|
|
59
|
+
|
|
60
|
+
Example prompts:
|
|
61
|
+
|
|
62
|
+
- "What is the CBI's official euro rate today, and how much did it change over the last week?"
|
|
63
|
+
- "Show the dollar rate every month since Farvardin 1404."
|
|
64
|
+
- "What is Iran's inflation now and how did it move in 1403?"
|
|
65
|
+
- "What did the central bank say about liquidity growth recently?"
|
|
66
|
+
- <span dir="rtl">نرخ رسمی دلار بانک مرکزی امروز چقدر است؟</span>
|
|
67
|
+
- <span dir="rtl">آخرین گزارش نماگرهای اقتصادی را بده.</span>
|
|
68
|
+
|
|
69
|
+
## Quick start
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
claude mcp add cbi -- uvx cbi-mcp
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Any client: command `uvx`, args `["cbi-mcp"]`. Behind a proxy set `CBI_MCP_PROXY=http://host:port`.
|
|
76
|
+
|
|
77
|
+
## Tools
|
|
78
|
+
|
|
79
|
+
| Tool | What it returns |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `cb_exchange_rates` | Official rates of ~48 currencies for a date (default latest), optional currency filter |
|
|
82
|
+
| `cb_rate_history` | One currency over time with change %; last 7 days, or sampled between two dates |
|
|
83
|
+
| `cb_inflation` | Monthly 12-month inflation for a Jalali year and annual inflation history |
|
|
84
|
+
| `cb_policy_rates` | Weekly interbank, repo and standing-facility rates for a year |
|
|
85
|
+
| `cb_news` | News titles (id, date), optional word filter and year |
|
|
86
|
+
| `cb_news_item` | Full text and attachments of one news item |
|
|
87
|
+
| `cb_liquidity` | Liquidity, money, quasi-money and monetary base (balance, yearly growth) from the newest monthly Excel, plus latest statements |
|
|
88
|
+
| `cb_publications` | Newest Economic Trends, monthly monetary reports, annual or interbank reviews with file links |
|
|
89
|
+
| `cb_statistics` | Rows of any sheet of the monthly Excel tables: monetary, balance_of_payments, fiscal, capital_market (year, month, sheet) |
|
|
90
|
+
| `cb_bond_auctions` | Results of the newest weekly government sukuk auctions per bond: offered, sold, yield |
|
|
91
|
+
| `cb_open_market` | Weekly open market operation reports with the newest repo auction figures |
|
|
92
|
+
|
|
93
|
+
## FAQ
|
|
94
|
+
|
|
95
|
+
**Is this the market rate?** No. These are the CBI's official reference rates; the free-market rate is not published there.
|
|
96
|
+
|
|
97
|
+
**Why no time-series search?** The bank's series database (tsd.cbi.ir) did not answer from any network tried.
|
|
98
|
+
|
|
99
|
+
**Does it read the Excel/PDF reports?** The monthly Excel statistics tables (`cb_statistics`, `cb_liquidity`), the weekly repo report and the auction results are read as numbers. Other Excel and PDF reports come back as links.
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
MIT. Unofficial; not affiliated with the Central Bank of the Islamic Republic of Iran. Data belongs to its publisher.
|
|
104
|
+
|
|
105
|
+
Built by Sepehr Radmard (سپهر رادمرد): github.com/sepehr071 · linkedin.com/in/sepehr-radmard
|
|
106
|
+
|
|
107
|
+
## فارسی
|
|
108
|
+
|
|
109
|
+
`cbi-mcp` یک سرور MCP غیررسمی و فقطخواندنی برای سایت بانک مرکزی جمهوری اسلامی ایران (cbi.ir) است: نرخ رسمی ارز و تاریخچه آن، نرخ تورم، نرخهای سود بازار بینبانکی، اخبار و اظهارات نقدینگی و فهرست گزارشها با پیوند دانلود. نیازی به کلید یا حساب نیست.
|
|
110
|
+
نصب: `claude mcp add cbi -- uvx cbi-mcp`
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "cbi-mcp"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Unofficial read-only MCP server for the Central Bank of Iran (cbi.ir): official exchange rates, inflation, policy rates, news."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [{ name = "Sepehr Radmard", email = "sepehrr80@gmail.com" }]
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
keywords = ["mcp", "model-context-protocol", "central-bank-of-iran", "cbi", "cbi-ir", "exchange-rate", "iran", "inflation", "liquidity", "interest-rate", "rial", "claude", "persian"]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 4 - Beta",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Operating System :: OS Independent",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3.10",
|
|
17
|
+
"Programming Language :: Python :: 3.11",
|
|
18
|
+
"Programming Language :: Python :: 3.12",
|
|
19
|
+
"Programming Language :: Python :: 3.13",
|
|
20
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
21
|
+
"Topic :: Office/Business :: Financial",
|
|
22
|
+
]
|
|
23
|
+
dependencies = [
|
|
24
|
+
"mcp>=2.2,<3",
|
|
25
|
+
"httpx>=0.27",
|
|
26
|
+
"httpx-curl-cffi>=0.1.5",
|
|
27
|
+
"curl-cffi>=0.16.3",
|
|
28
|
+
"xlrd>=2.0.1",
|
|
29
|
+
"pypdf>=5",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://github.com/sepehr071/cbi-mcp"
|
|
34
|
+
Issues = "https://github.com/sepehr071/cbi-mcp/issues"
|
|
35
|
+
Website = "https://mcpfarsi.ir/"
|
|
36
|
+
|
|
37
|
+
[project.scripts]
|
|
38
|
+
cbi-mcp = "cbi_mcp.server:main"
|
|
39
|
+
|
|
40
|
+
[dependency-groups]
|
|
41
|
+
dev = ["pytest>=8", "ruff>=0.6"]
|
|
42
|
+
|
|
43
|
+
[build-system]
|
|
44
|
+
requires = ["hatchling"]
|
|
45
|
+
build-backend = "hatchling.build"
|
|
46
|
+
|
|
47
|
+
[tool.pytest.ini_options]
|
|
48
|
+
testpaths = ["tests"]
|
|
49
|
+
addopts = "-m 'not live'"
|
|
50
|
+
markers = ["live: calls the real cbi.ir site (run with -m live)"]
|
|
51
|
+
|
|
52
|
+
[tool.ruff]
|
|
53
|
+
line-length = 120
|
|
54
|
+
target-version = "py310"
|
|
55
|
+
|
|
56
|
+
[tool.ruff.lint]
|
|
57
|
+
select = ["E", "F", "I", "B", "UP"]
|
|
58
|
+
ignore = ["E501"] # long Field(description=...) strings read better on one line
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.sepehr071/cbi-mcp",
|
|
4
|
+
"title": "Central Bank of Iran",
|
|
5
|
+
"description": "Read-only Central Bank of Iran (cbi.ir): official FX rates, inflation, policy rates, news.",
|
|
6
|
+
"repository": {
|
|
7
|
+
"url": "https://github.com/sepehr071/cbi-mcp",
|
|
8
|
+
"source": "github"
|
|
9
|
+
},
|
|
10
|
+
"websiteUrl": "https://github.com/sepehr071/cbi-mcp",
|
|
11
|
+
"version": "0.1.0",
|
|
12
|
+
"packages": [
|
|
13
|
+
{
|
|
14
|
+
"registryType": "pypi",
|
|
15
|
+
"registryBaseUrl": "https://pypi.org",
|
|
16
|
+
"identifier": "cbi-mcp",
|
|
17
|
+
"version": "0.1.0",
|
|
18
|
+
"runtimeHint": "uvx",
|
|
19
|
+
"transport": {
|
|
20
|
+
"type": "stdio"
|
|
21
|
+
},
|
|
22
|
+
"environmentVariables": [
|
|
23
|
+
{
|
|
24
|
+
"name": "CBI_MCP_PROXY",
|
|
25
|
+
"description": "Optional HTTP proxy URL for the cbi.ir requests; system proxy settings are ignored.",
|
|
26
|
+
"isRequired": false,
|
|
27
|
+
"isSecret": false
|
|
28
|
+
}
|
|
29
|
+
]
|
|
30
|
+
}
|
|
31
|
+
]
|
|
32
|
+
}
|