tsetmc-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tsetmc-mcp show me the order book for خودرو"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Open Stocks MCP
Features
Tool | What it does |
| نماد (Persian) → instrument code |
| live price, %change, volume/value, EPS/PE |
| 5-level صف خرید/فروش (bid/ask) |
| حقیقی/حقوقی buy/sell + net institutional |
| filtered/sorted whole-market view (never dumps ~700 rows) |
| top gainers/losers, most active, market breadth |
| TEDPIX + equal-weight index at a glance |
| daily OHLCV; large pulls → CSV file |
| is the Tehran market open now |
| field / units reference |
| run a custom filter (describe it, or paste a TSETMC filter) |
| run a saved filter or a built-in preset by name |
| 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
uvinstaller can provision it for you).uv— install withcurl -LsSf https://astral.sh/uv/install.sh | shThe 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 everythingStep 1 — verify it can reach TSETMC (run this in Iran)
uv run tsetmc-mcp-selfcheckRead 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-mcpThe
--directorymust 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-mcpVerify 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)>0Say "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-mcpTroubleshooting
Symptom | Cause / fix |
self-check is all 🚫 | non-Iranian IP — turn off any foreign VPN |
|
|
empty market_watch / screen | outside the Sat–Wed 09:00–12:30 session (market closed) |
self-check | it's Thursday/Friday (Tehran weekend) or a holiday — not an error |
| needs Python ≥ 3.13 + |
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 stateDevelop
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 InspectorContributions 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 و از همان مسیرهایی که خودِ وبسایت استفاده میکند، بهصورت فقط-خواندنی دریافت میکند؛ به هیچ منبع احرازهویتشده، پولی یا غیرعمومی دسترسی ندارد و هیچ سازوکار امنیتی را دور نمیزند.
این ابزار برای استفادهٔ شخصی، آموزشی و پژوهشی ارائه شده و بهصورت پیشفرض دارای محدودیت نرخ درخواست است؛ لطفاً مسئولانه استفاده کنید. دادهها «همانگونه که هست» و بدون هیچ تضمینی نسبت به صحت یا بهروزبودن ارائه میشوند و ممکن است نادرست باشند. هیچیک از موارد ارائهشده توصیهٔ مالی نیست و مسئولیت هرگونه استفاده بر عهدهٔ کاربر است.
Available Tools
13 toolsdescribe_fieldsB
Reference: what each field means and its units. Call once; don't repeat.
Inputs: no named parameters.
filter_helpA
Reference for writing filters: all variables (with meanings), operators, functions, the buy_queue()/sell_queue() sugar, built-in presets, and the user's saved filters. Call this before writing a filter so it uses valid names.
Inputs: no named parameters.
get_index_overviewA
Market 'at a glance' (در یک نگاه): TEDPIX (شاخص کل) and the equal-weighted index — last value and change — plus total market value and state.
Inputs: no named parameters.
get_market_watchA
Filtered/sorted view of the whole market (دیدهبان) from the live snapshot.
ALWAYS filtered and limited so it never dumps ~700 rows. sort_by ∈ {value, volume, pct_change, last, count}. Optional filters: min_pct/max_pct (percent change), min_volume, min_value, flow (1=Bourse, 2=Farabourse, 4=پایه), symbol_contains. fields projects specific columns (default is a compact set). Returns {rows, returned, matched, truncated, meta}.
Inputs: flow, limit, fields, max_pct, +6 more.
get_money_flowA
Individual-vs-institutional money flow (حقیقی/حقوقی) for one symbol.
Returns buy/sell volumes and counts split into individual (I / حقیقی) and legal (N / حقوقی), plus legal_net_volume (positive = institutional accumulation). Useful for 'smart money' (پول هوشمند) reads.
Inputs: symbol (required).
get_order_bookB
Live 5-level order book (صف خرید/فروش) for one symbol.
Each level has bid (تقاضا) and ask (عرضه) price, volume and order count. A heavy imbalance with an empty opposite side indicates a buy/sell queue. Fetched live per call (5 levels is the maximum depth TSETMC exposes).
Inputs: symbol (required).
get_price_historyA
Daily OHLCV history for one symbol (raw / unadjusted), newest last.
days<=0 means the full available history. Large pulls (or save_csv=True) are written to a CSV file and the response returns {file_path, summary, sample} instead of every row, to protect the context window. Prices in Rial.
Inputs: symbol (required), days, save_csv.
get_quoteA
Live price snapshot for one symbol (نماد or insCode).
Returns last/closing/open/high/low prices, % change vs. yesterday, traded volume & value, EPS, P/E and base volume. Prices are in Rial. Served from the in-memory market snapshot; check meta.market_open and meta.staleness_seconds to know how fresh it is.
Inputs: symbol (required).
market_status_toolA
Is the Tehran market open right now? Returns open/trading-day status, the current Tehran time, the session window, and the current snapshot freshness.
Inputs: no named parameters.
run_filterA
Run a custom stock filter over the live market and return matching symbols.
expression is a boolean condition over a symbol's fields. Accepts TSETMC filter
syntax — e.g. (ct).Buy_I_Volume-(ct).Sell_I_Volume>0 && (plp)>0 — OR friendly
aliases — e.g. net_individual > 0 and change_pct > 0. Call filter_help() first to
see all variables (price/volume/eps/pe, حقیقی-حقوقی ct_*, order-book, buy_queue()).
Order-book/صف filters enrich a shortlist on demand (capped by enrich_limit). Pass
save_as to store the filter under a name for reuse. Returns {rows, matched,
returned, normalized, tier, meta}.
Inputs: expression (required), limit, save_as, description, +1 more.
run_saved_filterC
Run a previously saved filter OR a built-in preset by name.
Presets include: up_liquid, net_individual_inflow, buyer_power_2x, code_to_code, institutional_accumulation, volume_spike, smart_money_lite, buy_queue, sell_queue. Unknown names return the list of available presets + saved filters.
Inputs: name (required), limit, enrich_limit.
screenB
Prebuilt market screens over the live snapshot.
kind ∈ {top_gainers, top_losers, most_active_value, most_active_volume, most_active_trades, market_breadth}. market_breadth returns advancers/ decliners/unchanged counts; the others return a ranked, limited list.
Inputs: kind, limit.
search_symbolA
Resolve a Tehran-exchange نماد (symbol) to its instrument code (insCode).
Accepts Persian text; Arabic ي/ك and Persian/Arabic digits are normalized automatically. Use this first when you only know the symbol name. Returns {results:[{ins_code, symbol, name}], meta}.
Inputs: query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool serves a clearly distinct purpose: reference, market overview, live snapshot, filtering, historical data, order book, etc. Even similar tools like get_market_watch, screen, and run_filter are differentiated by their descriptions (filtered view vs prebuilt screens vs custom filters). No ambiguity in tool selection.
Most tools follow a clear verb_noun pattern (e.g., get_quote, run_filter, search_symbol). However, 'market_status_tool' deviates by placing 'tool' at the end instead of using a verb prefix. This is a minor inconsistency in an otherwise coherent naming scheme.
With 13 tools, the server is well-scoped for a stock market data provider. Each tool adds necessary functionality without redundancy. The count is appropriate for covering quoting, history, order book, screening, filtering, symbols, and market status.
The tool set covers all essential operations for the domain: live quotes, historical data, order book, money flow, market overview, screening, filtering, symbol resolution, and market status. No obvious gaps; reference tools for fields and filters further enhance completeness.
Related MCP Connectors
MCP server for real-time China A-share stock quotes, indices and market data.
MCP server with quote and live cryptocurrency price tools, local and cloud-deployed transports.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Hosted MCP server for Indian market quotes, option-chain Greeks and multi-broker telemetry.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server that provides KOSPI/KOSDAQ stock data using FastMCP.6186 PyPI75MIT
- AlicenseCqualityDmaintenanceAn MCP server providing stock market data and trading capabilities through multiple broker APIs including Robinhood and Schwab.10070 PyPI11Apache 2.0
- AlicenseAqualityDmaintenanceMCP server for Indian stock market data. Provides 16 tools for quotes, history, fundamentals, mutual funds, indices, corporate actions, options, IPOs, and portfolio analysis.1690 npm5MIT
- AlicenseAqualityBmaintenanceAn MCP server providing real-time market data, technical analysis, prediction market odds, and strategy backtesting for crypto, equities, and prediction markets.20MIT