ime-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.
Files changed (42) hide show
  1. ime_mcp-0.1.0/.github/workflows/ci.yml +22 -0
  2. ime_mcp-0.1.0/.github/workflows/publish.yml +51 -0
  3. ime_mcp-0.1.0/.gitignore +6 -0
  4. ime_mcp-0.1.0/LICENSE +21 -0
  5. ime_mcp-0.1.0/PKG-INFO +301 -0
  6. ime_mcp-0.1.0/README.md +273 -0
  7. ime_mcp-0.1.0/pyproject.toml +56 -0
  8. ime_mcp-0.1.0/server.json +32 -0
  9. ime_mcp-0.1.0/src/ime_mcp/__init__.py +5 -0
  10. ime_mcp-0.1.0/src/ime_mcp/http.py +270 -0
  11. ime_mcp-0.1.0/src/ime_mcp/ime.py +646 -0
  12. ime_mcp-0.1.0/src/ime_mcp/registry.py +16 -0
  13. ime_mcp-0.1.0/src/ime_mcp/securities.py +353 -0
  14. ime_mcp-0.1.0/src/ime_mcp/server.py +95 -0
  15. ime_mcp-0.1.0/tests/conftest.py +78 -0
  16. ime_mcp-0.1.0/tests/fixtures/board_gavahi.json +1 -0
  17. ime_mcp-0.1.0/tests/fixtures/board_salaf.json +1 -0
  18. ime_mcp-0.1.0/tests/fixtures/board_sandoq.json +1 -0
  19. ime_mcp-0.1.0/tests/fixtures/cdc_contracts.json +1 -0
  20. ime_mcp-0.1.0/tests/fixtures/cdc_trades.json +1 -0
  21. ime_mcp-0.1.0/tests/fixtures/chart.json +3 -0
  22. ime_mcp-0.1.0/tests/fixtures/export.json +173 -0
  23. ime_mcp-0.1.0/tests/fixtures/export_supply.json +1 -0
  24. ime_mcp-0.1.0/tests/fixtures/finance.json +1 -0
  25. ime_mcp-0.1.0/tests/fixtures/grid_export.json +3 -0
  26. ime_mcp-0.1.0/tests/fixtures/grid_halls.json +3 -0
  27. ime_mcp-0.1.0/tests/fixtures/grid_markets.json +3 -0
  28. ime_mcp-0.1.0/tests/fixtures/main_groups.json +3 -0
  29. ime_mcp-0.1.0/tests/fixtures/news.html +1 -0
  30. ime_mcp-0.1.0/tests/fixtures/options.json +1 -0
  31. ime_mcp-0.1.0/tests/fixtures/premium_supply.json +1 -0
  32. ime_mcp-0.1.0/tests/fixtures/premium_trades.json +1 -0
  33. ime_mcp-0.1.0/tests/fixtures/producers.json +3 -0
  34. ime_mcp-0.1.0/tests/fixtures/rate.json +3 -0
  35. ime_mcp-0.1.0/tests/fixtures/sub_groups.json +3 -0
  36. ime_mcp-0.1.0/tests/fixtures/supply.json +164 -0
  37. ime_mcp-0.1.0/tests/fixtures/trades_physical.json +3 -0
  38. ime_mcp-0.1.0/tests/fixtures/trades_subsidiary.json +3 -0
  39. ime_mcp-0.1.0/tests/fixtures/weekly.html +5 -0
  40. ime_mcp-0.1.0/tests/test_ime.py +320 -0
  41. ime_mcp-0.1.0/tests/test_live_ime.py +129 -0
  42. ime_mcp-0.1.0/uv.lock +1362 -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/ime-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
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ .pytest_cache/
6
+ .ruff_cache/
ime_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.
ime_mcp-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,301 @@
1
+ Metadata-Version: 2.5
2
+ Name: ime-mcp
3
+ Version: 0.1.0
4
+ Summary: Unofficial read-only MCP server for the Iran Mercantile Exchange (ime.co.ir): physical market trades, supply offers, prices, market totals.
5
+ Project-URL: Homepage, https://github.com/sepehr071/ime-mcp
6
+ Project-URL: Issues, https://github.com/sepehr071/ime-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: bourse-kala,claude,commodities,commodity-exchange,ime,iran,iran-mercantile-exchange,mcp,model-context-protocol,persian,petrochemical,steel
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
+ Description-Content-Type: text/markdown
28
+
29
+ <!-- mcp-name: io.github.sepehr071/ime-mcp -->
30
+
31
+ <div align="center">
32
+
33
+ # ime-mcp: Iran Mercantile Exchange (بورس کالای ایران) MCP server for AI agents
34
+
35
+ **ime-mcp is an unofficial, read-only MCP server that gives AI agents the public trade and supply data of the Iran Mercantile Exchange (IME, ime.co.ir).**<br>
36
+ Its 14 tools list commodity trades (steel, petrochemicals, cement, oil products, metals, agriculture) with prices and volumes,<br>
37
+ upcoming supply offers, daily price series, rankings by producer and broker, market and hall totals, the USD settlement rate,<br>
38
+ the options board, gold, silver and other deposit certificates, gold funds and exchange news and weekly reports.<br>
39
+ No API key or account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
40
+
41
+ [![PyPI](https://img.shields.io/pypi/v/ime-mcp?color=2563eb)](https://pypi.org/project/ime-mcp/)
42
+ [![Python](https://img.shields.io/pypi/pyversions/ime-mcp)](https://pypi.org/project/ime-mcp/)
43
+ [![CI](https://github.com/sepehr071/ime-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/ime-mcp/actions/workflows/ci.yml)
44
+ [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fime--mcp-7c3aed)](https://registry.modelcontextprotocol.io/?q=ime-mcp)
45
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/ime-mcp/blob/main/LICENSE)
46
+
47
+ [For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
48
+
49
+ </div>
50
+
51
+ ---
52
+
53
+ ## For AI agents
54
+
55
+ - **What:** unofficial MCP server (model context protocol) for ime.co.ir, the Iranian commodity exchange: physical market trades (industrial and mineral, petrochemical and oil products, cement, subsidiary market, Kish export hall), supply offers (including premium and export), price history, rankings by producer or broker, market totals, USD rate, news, weekly report links, the options board, deposit certificates (gold bar, gold coin, silver...), salaf and commodity funds.
56
+ - **Install:** `uvx ime-mcp` or `claude mcp add ime -- uvx ime-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
57
+ - **Auth:** none. Optional `IME_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
58
+ - **Access:** read-only. It cannot trade or place orders, so no confirmation is needed before calling any tool.
59
+ - **Tools:** 14, all prefixed `ime_`. Typical sequences: `ime_categories` -> `ime_price_history` / `ime_trades` / `ime_supply`; `ime_producers` -> `ime_trades`; `ime_options` -> `ime_options(contract=...)`; `ime_certificates` -> `ime_certificates(commodity=...)`.
60
+ - **Use when:** the user asks what traded on the exchange, the price of steel, rebar, hot sheet, polymers, bitumen or cement, what will be offered next session, how big trading was, the exchange's USD rate, option contracts, or gold bar, gold coin and silver certificate prices.
61
+ - **Do not use when:** the question is about the stock market (TSETMC), or real estate and car trading: those are not covered here.
62
+ - **Output:** compact JSON. Dates are Persian (`1405/08/09`); Gregorian input is accepted. Prices are Rial (per kg for goods counted in tonnes: check `unit`); `value_k_rial` is thousand Rial; summary values are million Rial; `value_rial` (options, certificates, funds) is Rial. Text is Persian.
63
+ - **Machine-readable:** [`server.json`](https://github.com/sepehr071/ime-mcp/blob/main/server.json) and the
64
+ [iran-mcp catalog](https://github.com/sepehr071/iran-mcp).
65
+
66
+ ## Why
67
+
68
+ The IME site shows trades and supply only through filter forms and paged tables. "How did the hot sheet price move
69
+ this month?" means picking the group, the subgroup and a date range, then reading the table row by row. With
70
+ `ime-mcp` an agent does it in one call:
71
+
72
+ > **You:** How did hot sheet prices move since the start of Aban?
73
+ >
74
+ > **Agent:** *calls* `ime_price_history(search="ورق گرم", date_from="1405/08/01")`
75
+ >
76
+ > Kavian hot sheet (KAS-HS00000-00) traded at 1,305,425 Rial/kg on 08/02 (3,740 t), 1,296,722 on 08/03 (1,430 t),
77
+ > 1,370,586 on 08/06 (2,310 t) and 1,352,960 on 08/09 (110 t).
78
+
79
+ <sub>Numbers from a live call on 2026-10-31.</sub>
80
+
81
+ ## What it can do
82
+
83
+ - **Trades**: every trade of a date range in the physical market, the subsidiary market (بازار فرعی) or the Kish export hall, with the weighted closing price, low and high, supply, demand, volume, value, producer, contract type, delivery and broker; filter by commodity group, producer or text
84
+ - **Supply offers** (اطلاعیه عرضه): what is up for sale in coming sessions with volume, base price, delivery place and date, settlement and broker
85
+ - **Price history**: daily low, high, volume-weighted average and volume per symbol over up to 45 days
86
+ - **Market totals**: value and volume by market and hall for a range, plus the USD settlement rate; day-by-day totals of one market
87
+ - **Rankings**: producers, commodities, brokers or halls ordered by traded value with market share
88
+ - **Options**: the options board (gold, gold coin, gold funds, saffron futures) with settlement prices and open interest, and the history of one contract
89
+ - **Certificates and funds**: gold bar, gold coin, silver, copper and steel deposit certificates, saffron certificates, salaf and gold funds, daily and with a bid/ask board
90
+ - **Groups and producers**: the exchange's commodity group tree and producer ids
91
+ - **News and reports**: the latest announcements and links to the weekly report PDFs
92
+
93
+ Example prompts:
94
+
95
+ - "What were the biggest trades on the exchange today?"
96
+ - "How did rebar prices move over the last two weeks?"
97
+ - "What is offered on the exchange next week from Mobarakeh Steel?"
98
+ - "How much did the physical market trade this week, by hall?"
99
+ - <span dir="rtl">قیمت ورق گرم در بورس کالا در یک ماه گذشته چطور تغییر کرده؟</span>
100
+ - <span dir="rtl">فردا چه محصولاتی در بورس کالا عرضه می‌شود؟</span>
101
+
102
+ ## Quick start
103
+
104
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
105
+
106
+ <details open>
107
+ <summary><b>Claude Code</b></summary>
108
+
109
+ ```bash
110
+ claude mcp add ime -- uvx ime-mcp
111
+ ```
112
+ </details>
113
+
114
+ <details>
115
+ <summary><b>Claude Desktop</b></summary>
116
+
117
+ Settings → Developer → Edit Config, then add:
118
+
119
+ ```json
120
+ {
121
+ "mcpServers": {
122
+ "ime": { "command": "uvx", "args": ["ime-mcp"] }
123
+ }
124
+ }
125
+ ```
126
+ </details>
127
+
128
+ <details>
129
+ <summary><b>Cursor, VS Code, Codex CLI, Gemini CLI, Windsurf</b></summary>
130
+
131
+ Use the same command (`uvx ime-mcp`) in your client's MCP settings, for example `codex mcp add ime -- uvx ime-mcp`
132
+ or the Claude Desktop block above in `~/.cursor/mcp.json`.
133
+ </details>
134
+
135
+ <details>
136
+ <summary><b>Anything else</b></summary>
137
+
138
+ It is a standard stdio MCP server: run `uvx ime-mcp`, or `pip install ime-mcp` and run `ime-mcp`.
139
+ </details>
140
+
141
+ ## Tools
142
+
143
+ Group ids come from `ime_categories`, producer ids from `ime_producers`. Dates are `1405/08/09` or `2026-10-31`; the
144
+ default is today (Tehran time). Ranges are limited to 45 days.
145
+
146
+ | Tool | What it does |
147
+ |---|---|
148
+ | `ime_categories` | List the exchange's commodity groups: main groups, then groups, then subgroups, with their ids |
149
+ | `ime_producers` | Find producers and suppliers listed on the exchange by name, to get the producer id for the trade and supply tools |
150
+ | `ime_trades` | List commodity trades (price, volume, supply, demand, buyer broker) for a date range, with totals |
151
+ | `ime_supply` | List supply offers (اطلاعیه عرضه): what is up for sale on which session, volume and base price (physical, premium or export) |
152
+ | `ime_price_history` | Daily price series (low, high, volume-weighted average, volume) per symbol over a date range |
153
+ | `ime_market_summary` | Exchange-wide trade value and volume for a date range: by market, by physical-market hall, plus the USD rate |
154
+ | `ime_daily_totals` | Day-by-day trade value and volume of one market over a date range (the site's market chart) |
155
+ | `ime_news` | Latest news and notices from the exchange's news archive: title, lead, date and link |
156
+ | `ime_trade_stats` | Rank producers, commodities, brokers or halls by traded value over a date range, with each one's market share |
157
+ | `ime_weekly_reports` | List the exchange's weekly market reports (گزارش هفتگی), newest first, with the PDF link of each |
158
+ | `ime_options` | Options on gold, gold coin, gold funds and saffron futures (اختیار معامله): one day's board or one contract's history |
159
+ | `ime_securities` | Daily trades of the exchange's financial-market symbols: salaf, commodity deposit certificates and commodity funds |
160
+ | `ime_certificates` | Continuous commodity deposit certificates (گواهی سپرده پیوسته): gold bar, gold coin, silver, copper, steel and more |
161
+ | `ime_board` | Market-view board (cdn.ime.co.ir) with the best bid and ask for funds, certificates and salaf |
162
+
163
+ All 14 tools are annotated `readOnlyHint: true`.
164
+
165
+ ## How it works
166
+
167
+ ```text
168
+ AI agent (Claude, Cursor, Copilot, ...)
169
+ │
170
+ │ MCP over stdio
171
+ ▼
172
+ ime-mcp (runs on your machine)
173
+ │
174
+ │ HTTPS
175
+ └──────▶ www.ime.co.ir imedata.asmx, auction.ashx, export.ashx, news archive
176
+ ```
177
+
178
+ `ime-mcp` runs locally and calls the same public endpoints the ime.co.ir pages use, with no hosted server in between
179
+ and no API key. Requests go out through a Chrome-impersonating client. It makes at most 3 requests at a time with a
180
+ little jitter, keeps answers for 2 minutes, retries a failed request up to twice, and only talks to www.ime.co.ir, dataapi.ime.co.ir (gold and other deposit certificates) and cdn.ime.co.ir (bid/ask board).
181
+
182
+ ## Good to know
183
+
184
+ - **Iranian network.** ime.co.ir answers from Iran. From a Turkish exit it timed out in testing; use a direct Iranian line or set `IME_MCP_PROXY` to a proxy that can reach it.
185
+ - **The site mixes up the physical and subsidiary lists.** Its trade-list service keeps the first answer per date range and then ignores the market flag. The server asks for a fresh (padded) date range and checks the halls, retrying up to 6 times, so a slow answer is normal.
186
+ - **Units.** Prices are Rial per kg for goods listed in tonnes. `value_k_rial` is price x volume in thousand Rial; market summaries are million Rial; options, securities, certificates and boards give `value_rial` in Rial.
187
+ - **Trading days.** Saturday to Wednesday and some Thursdays; other days return nothing.
188
+ - **Not covered:** real estate, car trading and the stock sub-sites are separate ime.co.ir sub-sites. Statistical report archives (market-reports.html) need a form post and are not read; weekly report PDFs are linked, not parsed. The subsidiary market list has no price or value, only base price, supply, demand and volume.
189
+ - **Persian data.** Names, halls, contracts and news come back in Persian.
190
+
191
+ ## FAQ
192
+
193
+ <details>
194
+ <summary><b>Is there an official IME API?</b></summary>
195
+
196
+ IME publishes data through its website only. `ime-mcp` is a separate, unofficial MCP server that calls the public
197
+ endpoints behind the website's tables and charts and returns compact JSON.
198
+ </details>
199
+
200
+ <details>
201
+ <summary><b>Does it need an API key or account?</b></summary>
202
+
203
+ No. Install with `uvx ime-mcp` and it works from an Iranian network.
204
+ </details>
205
+
206
+ <details>
207
+ <summary><b>Can it show live prices?</b></summary>
208
+
209
+ It shows trades published on the site, including the current session as the site lists them. It is not a tick feed.
210
+ </details>
211
+
212
+ <details>
213
+ <summary><b>Can it place orders?</b></summary>
214
+
215
+ No. It only reads public data.
216
+ </details>
217
+
218
+ <details>
219
+ <summary><b>How do I debug what the agent sees?</b></summary>
220
+
221
+ ```bash
222
+ npx @modelcontextprotocol/inspector uvx ime-mcp
223
+ ```
224
+ </details>
225
+
226
+ ## Configuration
227
+
228
+ | Variable | Default | Meaning |
229
+ |---|---|---|
230
+ | `IME_MCP_PROXY` | unset | Optional HTTP proxy URL for the ime.co.ir requests; system proxy settings are ignored. A comma-separated list is used one at a time: the next proxy takes over when one is blocked or cannot connect |
231
+
232
+ <a id="فارسی"></a>
233
+
234
+ ## فارسی: سرور MCP بورس کالای ایران
235
+
236
+ <div dir="rtl">
237
+
238
+ **سرور ime-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای [بورس کالای ایران](https://www.ime.co.ir) است. با آن دستیار هوش مصنوعی شما همان داده‌های عمومی سایت را می‌بیند: معاملات، قیمت‌ها، عرضه‌های پیش‌رو و آمار بازار.
239
+
240
+ **چه کارهایی می‌کند**
241
+
242
+ - **معاملات** بازار فیزیکی، بازار فرعی و تالار صادراتی کیش برای هر بازهٔ تاریخی، با قیمت پایانی (میانگین موزون)، کمترین و بیشترین قیمت، عرضه، تقاضا، حجم، ارزش، تولیدکننده و کارگزار.
243
+ - **اطلاعیهٔ عرضه** جلسه‌های پیش‌رو با حجم و قیمت پایه.
244
+ - **سابقهٔ قیمت** هر نماد به‌صورت روزانه تا ۴۵ روز.
245
+ - **آمار بازار** بر اساس بازار و تالار، و نرخ دلار تسویهٔ بورس.
246
+ - **اخبار** و گزارش‌های هفتگی بورس کالا.
247
+
248
+ **نکته‌ها:** فقط‌خواندنی است و سفارشی ثبت نمی‌کند؛ کلید API نمی‌خواهد؛ سایت بورس کالا فقط از شبکهٔ ایران پاسخ می‌دهد؛ معاملات سکه و گواهی طلا در زیرسایت دیگری هستند و پوشش داده نمی‌شوند.
249
+
250
+ **نصب** (اول [uv](https://docs.astral.sh/uv/getting-started/installation/) را نصب کنید). در Claude Code:
251
+
252
+ </div>
253
+
254
+ ```bash
255
+ claude mcp add ime -- uvx ime-mcp
256
+ ```
257
+
258
+ <div dir="rtl">
259
+
260
+ **نمونه پرسش‌ها**
261
+
262
+ - «قیمت ورق گرم در بورس کالا در یک ماه گذشته چطور تغییر کرده؟»
263
+ - «فردا چه محصولاتی در بورس کالا عرضه می‌شود؟»
264
+ - «بزرگ‌ترین معاملات امروز بورس کالا کدام‌اند؟»
265
+
266
+ </div>
267
+
268
+ ## Development
269
+
270
+ ```bash
271
+ git clone https://github.com/sepehr071/ime-mcp && cd ime-mcp
272
+ uv sync
273
+ uv run ruff check . && uv run ruff format --check .
274
+ uv run python -m pytest -q # offline unit tests on recorded IME answers
275
+ uv run python -m pytest -m live -q # calls the real ime.co.ir (needs an Iranian line)
276
+ uv build
277
+ ```
278
+
279
+ The physical-market tools live in `src/ime_mcp/ime.py`, the derivatives and securities tools in `src/ime_mcp/securities.py`; each is a typed async function with a docstring that tells the agent when to
280
+ use it. Issues and PRs are welcome.
281
+
282
+ Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions publishes to PyPI.
283
+
284
+ ## Related servers
285
+
286
+ - [iran-mcp](https://github.com/sepehr071/iran-mcp): catalog of all Iranian-service MCP servers
287
+ - [mcpfarsi.ir](https://mcpfarsi.ir/): Persian marketplace of MCP servers for Iranian services
288
+
289
+ ## Disclaimer
290
+
291
+ Unofficial and not affiliated with or endorsed by the Iran Mercantile Exchange. It is read-only and uses the public
292
+ endpoints of the ime.co.ir website, which can change without notice. Not investment advice; check prices on the
293
+ exchange before acting on them.
294
+
295
+ ## Author
296
+
297
+ Built and maintained by **Sepehr Radmard** (سپهر رادمرد). Connect on [LinkedIn](https://www.linkedin.com/in/sepehr-radmard) or follow [@sepehr071 on GitHub](https://github.com/sepehr071) for more MCP servers for Iranian websites, all listed in [iran-mcp](https://github.com/sepehr071/iran-mcp). If this saves you time, a star on the repo helps other people find it.
298
+
299
+ ## License
300
+
301
+ [MIT](https://github.com/sepehr071/ime-mcp/blob/main/LICENSE)