tsetmc-mcp

A local MCP server that gives Claude Code (and any MCP client) live Tehran Stock Exchange (TSETMC) market data — quotes, order-book queues (صف), حقیقی/حقوقی money-flow, market screens, price history, and custom filters you describe in plain language. Ask Claude about the بازار and it pulls the data for you.

It reads public data straight from tsetmc.com. It is not affiliated with TSETMC, needs no API key, and is read-only.

---

⚠️ One hard requirement: run it on an Iranian IP

tsetmc.com serves its data API to Iranian IPs and blocks most foreign / VPN addresses. Run this on a machine in Iran, and make sure the process is not routed through a foreign VPN. From inside Iran it just works — no proxy needed. Outside Iran it is not supported (you would need your own in-Iran relay).

The Tehran session is Saturday–Wednesday, 09:00–12:30 (Asia/Tehran). Outside those hours the market is closed: live prices read as empty and money-flow/صف filters return nothing until the session opens. That's expected, not a bug.

---

Features

Tool	What it does
search_symbol	نماد (Persian) → instrument code
get_quote	live price, %change, volume/value, EPS/PE
get_order_book	5-level صف خرید/فروش (bid/ask)
get_money_flow	حقیقی/حقوقی buy/sell + net institutional
get_market_watch	filtered/sorted whole-market view (never dumps ~700 rows)
screen	top gainers/losers, most active, market breadth
get_index_overview	TEDPIX + equal-weight index at a glance
get_price_history	daily OHLCV; large pulls → CSV file
market_status	is the Tehran market open now
describe_fields	field / units reference
run_filter	run a custom filter (describe it, or paste a TSETMC filter)
run_saved_filter	run a saved filter or a built-in preset by name
filter_help	filter variables, operators, presets

Prices are in Rial. Every response is stamped with freshness (market_open, staleness_seconds, upstream_reachable) so the model never treats stale data as live.

---

Prerequisites

• A machine in Iran (see above), not on a foreign VPN.
• Python ≥ 3.11 (the uv installer can provision it for you).
• uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh
• The Claude Code CLI (claude), or any MCP client.

Get the code & install

git clone https://github.com/solitraderbusiness/tsetmc-mcp
cd tsetmc-mcp
uv sync            # creates .venv and installs everything

Step 1 — verify it can reach TSETMC (run this in Iran)

uv run tsetmc-mcp-selfcheck

Read the result:

• mostly ✅ → you're good, continue.
• all 🚫 BLOCKED → you're on a non-Iranian IP. Turn off any foreign VPN and re-run.
• ✅ but WARN calendar trading_day=False / 0 traded → fine, the market is just closed. Reachability is proven; continue.

Step 2 — register it with Claude Code

Run this from inside the clone so the absolute path is filled in for you:

claude mcp add tsetmc -- uv run --directory "$(pwd)" tsetmc-mcp

The --directory must be an absolute path. A relative or ~ path is the #1 cause of a server that registers "successfully" but then shows disconnected.

Alternative — one line, no clone (once the repo is public; you can't run the Iran-IP selfcheck first this way):

claude mcp add tsetmc -- uvx --from 'git+https://github.com/solitraderbusiness/tsetmc-mcp@v0.1.0' tsetmc-mcp

Verify it worked

Restart Claude Code and run /mcp — you should see tsetmc connected. Ask Claude "is the Tehran market open?" — a stamped market_status reply confirms it's live.

---

Usage — just talk to Claude

Ask in plain Persian or English; Claude picks the right tool:

• «قیمت فولاد چنده؟» / "what's فولاد trading at?"
• «صف خرید خودرو چطوره؟» / "show خودرو's order book"
• «امروز کدوم نمادها +۳٪ با حجم بالان؟» / "stocks up >3% on high volume"
• «بیشترین رشد امروز» / "top gainers now"
• «حقیقی/حقوقی شستا؟» / "smart-money on شستا"
• «شاخص کل چنده؟» / "where's TEDPIX?"
• «تاریخچه ۶ ماه فولاد» / "pull فولاد's price history" (large pulls saved to CSV)

Custom filters — describe it, Claude writes it, runs it

TSETMC's "دیده‌بان فیلتر" lets you write filter scripts. This does the same, but you just describe what you want:

«سهم‌هایی که پول حقیقی واردشون میشه و مثبت‌ان» → Claude writes net_individual > 0 and change_pct > 0, runs it, lists the matches.

• Paste a real TSETMC filter and it runs as-is: (ct).Buy_I_Volume-(ct).Sell_I_Volume>0 && (plp)>0
• Say "save this as my-flow" → later "run my-flow".
• Built-in presets: buyer_power_2x (پول داغ), code_to_code (کد به کد), institutional_accumulation, volume_spike, buy_queue/sell_queue (صف), …
• Safety: filters are parsed, never executed as code — no filter string can run code or touch your system.
• Not in v1: 30-day-average / RSI history terms and market-cap/sector (Claude will say so and suggest an alternative). Filters are most useful during market hours.

---

How it works

A background poller pulls the whole market from TSETMC every few seconds during the Tehran session and keeps it in memory. Every tool answers from that snapshot, so asking Claude a question never hammers TSETMC (which would get you rate-limited / IP-blocked). Order books and history are fetched per-symbol on demand. Full architecture: docs/design.md; endpoint reference: docs/endpoints.md.

Configuration

Everything has a safe default; override via env vars (see .env.example) — poll interval, request rate, market hours, output limits, data dir. Extra market holidays: put one YYYY-MM-DD per line in ~/.tsetmc-mcp/holidays.txt (weekends Thu/Fri are already handled). Pass env to the server via claude mcp add --env KEY=value ….

Optional: the 5j9/tsetmc accelerator

The default raw backend needs no extra packages. On Python ≥ 3.13 you can opt into the actively-maintained 5j9/tsetmc library as an alternate backend behind the same interface:

uv pip install "tsetmc>=3.0"
TSETMC_SOURCE=library uv run tsetmc-mcp

Troubleshooting

Symptom	Cause / fix
self-check is all 🚫	non-Iranian IP — turn off any foreign VPN
/mcp shows tsetmc disconnected	--directory was relative/~ — re-add with an absolute path ("$(pwd)" from the clone)
empty market_watch / screen	outside the Sat–Wed 09:00–12:30 session (market closed)
self-check WARN trading_day=False	it's Thursday/Friday (Tehran weekend) or a holiday — not an error
TSETMC_SOURCE=library errors	needs Python ≥ 3.13 + pip install "tsetmc>=3.0"

Update / uninstall

git -C tsetmc-mcp pull && uv sync   # update
claude mcp remove tsetmc            # unregister
# delete the clone and ~/.tsetmc-mcp/ to remove all local state

Develop

uv run pytest         # 107 offline tests (no network needed)
uv run ruff check . && uv run ruff format --check .
uv run mcp dev src/tsetmc_mcp/server.py   # click-test tools in the MCP Inspector

Contributions welcome — see CONTRIBUTING.md. Security reports: SECURITY.md. Your requests go directly from your machine to tsetmc.com; this tool sends nothing anywhere else.

License

MIT. The optional library extra pulls 5j9/tsetmc (GPL-3.0); it is not vendored or bundled here — it's only an optional dependency specifier that pip fetches from PyPI if you opt in, so it places no copyleft obligation on this MIT distribution. (Don't bake an installed tsetmc into a distributed Docker image / single-file binary, or that bundle becomes a GPL combined work.)

---

Disclaimer

This project is an independent, open-source client. It is NOT affiliated with, endorsed by, or connected to the Tehran Securities Exchange Technology Management Co. (TSETMC), the Tehran Stock Exchange, or any regulatory body.

It reads PUBLICLY available market data from tsetmc.com through the same undocumented endpoints the website itself uses. All requests are READ-ONLY. It accesses no authenticated, paywalled, or non-public resource and circumvents no access control.

It is provided for personal, educational, and research use, and is rate-limited by design; please use it responsibly and do not send abusive request volumes. You are responsible for how you use it and for complying with any applicable terms of use and local laws.

The data is provided "AS IS", without any warranty of accuracy, completeness, or timeliness, and may be delayed or incorrect. Nothing here is financial or investment advice. The authors accept no liability for any loss arising from use of this software or the data it retrieves.

سلب مسئولیت

این ابزار یک کلاینت متن‌باز و مستقل است و هیچ وابستگی، تأییدیه یا ارتباطی با شرکت مدیریت فناوری بورس تهران (TSETMC)، بورس اوراق بهادار تهران یا هیچ نهاد ناظری ندارد.

این کتابخانه صرفاً داده‌های عمومی و در دسترسِ همگان را از tsetmc.com و از همان مسیرهایی که خودِ وب‌سایت استفاده می‌کند، به‌صورت فقط-خواندنی دریافت می‌کند؛ به هیچ منبع احرازهویت‌شده، پولی یا غیرعمومی دسترسی ندارد و هیچ سازوکار امنیتی را دور نمی‌زند.

این ابزار برای استفادهٔ شخصی، آموزشی و پژوهشی ارائه شده و به‌صورت پیش‌فرض دارای محدودیت نرخ درخواست است؛ لطفاً مسئولانه استفاده کنید. داده‌ها «همان‌گونه که هست» و بدون هیچ تضمینی نسبت به صحت یا به‌روزبودن ارائه می‌شوند و ممکن است نادرست باشند. هیچ‌یک از موارد ارائه‌شده توصیهٔ مالی نیست و مسئولیت هرگونه استفاده بر عهدهٔ کاربر است.