tsetmc-mcp
Advanced tools
Unofficial read-only MCP server for the Tehran Stock Exchange (tsetmc.com): quotes, market movers, order book, history, indices.
Let your AI agent read the Tehran Stock Exchange (بورس تهران).
An unofficial, read-only MCP server for TSETMC, the data portal of the Tehran Stock Exchange and Iran Fara Bourse:
quotes, top movers, order book, daily history, real vs legal trading and market indices, from Claude, Cursor or Copilot.
For AI agents · Quick start · What it can do · Tools · FAQ · فارسی
uvx tsetmc-mcp or claude mcp add tsetmc -- uvx tsetmc-mcp. Transport: stdio. Needs uv (Python 3.10+).TSETMC_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.ts_. Typical sequence: ts_indices -> ts_market_movers -> ts_get_quote -> ts_price_history.
If you only have a name, call ts_search_symbols first and pass its symbol or ins_code to the other tools.YYYY-MM-DD).TSETMC_MCP_PROXY.server.json and the
awesome-iran-mcp catalog.TSETMC is the place Iranian traders look at, but it is a heavy web page built for human eyes. Asking "which sectors
are up today, which stocks hit the daily limit, and are individual investors buying or selling Foolad?" means opening
several screens. With tsetmc-mcp an agent answers it in a few calls and returns a short summary instead of tables
of raw numbers.
You: How is the market today, and what are the biggest gainers?
Agent: calls
ts_indices(limit=5)->ts_market_movers(market="bourse", sort_by="gain", limit=5)It reads the total index, the market state and the strongest sector indices, then lists the top gainers with their last price, change and whether they are stuck at the upper price limit.
Every reply is trimmed to stay under about 15 KB, so it does not flood the agent's context.
Example prompts:
You need uv. No API key or account.
claude mcp add tsetmc -- uvx tsetmc-mcp
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"tsetmc": { "command": "uvx", "args": ["tsetmc-mcp"] }
}
}
Add the Claude Desktop block above to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Click Install in VS Code above, or add to .vscode/mcp.json:
{
"servers": {
"tsetmc": { "type": "stdio", "command": "uvx", "args": ["tsetmc-mcp"] }
}
}
codex mcp add tsetmc -- uvx tsetmc-mcp
Or in ~/.codex/config.toml:
[mcp_servers.tsetmc]
command = "uvx"
args = ["tsetmc-mcp"]
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"tsetmc": { "command": "uvx", "args": ["tsetmc-mcp"] }
}
}
Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It is a standard stdio MCP server: run uvx tsetmc-mcp, or pip install tsetmc-mcp and run tsetmc-mcp.
Pass a ticker (فولاد), an exact name, or a numeric ins_code as symbol. Index tools take an index name such as شاخص کل.
| Tool | What it does |
|---|---|
ts_search_symbols | Find Tehran Stock Exchange instruments (shares, funds, rights, bonds) by ticker or name |
ts_get_quote | Latest price, daily range, volume and key facts of one instrument on the Tehran Stock Exchange |
ts_market_movers | Top traded instruments of a market today, ranked by gain, loss, volume, value or trade count |
ts_order_book | Best five bid and ask levels (price, volume, order count) of one instrument |
ts_price_history | Daily open, high, low, close, volume, trades and value of one instrument for its latest trading days, newest first |
ts_real_legal | Buy and sell volume, value and buyer/seller counts split by real (individual) and legal (institutional) traders per day |
ts_indices | TSE total index, market state and trading totals, plus every sector and market index with its change |
ts_index_history | Daily close, high, low and percent change of a TSE index (total, equal-weight, sector...), newest first |
All 8 tools are annotated readOnlyHint: true.
AI agent (Claude, Cursor, Copilot, ...)
│
│ MCP over stdio
▼
tsetmc-mcp (runs on your machine)
│
│ HTTPS
└──────▶ cdn.tsetmc.com quotes, market watch, order book, indices
tsetmc-mcp runs locally and calls the same endpoints the tsetmc.com site uses. It has no hosted server in between
and no API key. The TSETMC API is undocumented and blocks plain HTTP clients, so requests go out through a
Chrome-impersonating client. It sends at most 2 requests at a time with a little jitter, keeps answers for 15 seconds,
retries a failed GET up to twice, and only talks to cdn.tsetmc.com. It only reads.
last vs close: last is the last trade, close the closing (volume-weighted) price; change_pct compares last with yesterday's close.TSETMC_MCP_PROXY to an HTTP proxy with an Iranian exit. System proxy variables are ignored on purpose.ts_market_movers returns at most 30 rows, ts_price_history 50 days, ts_index_history 100 days, ts_real_legal 10 days, ts_indices 60 indices.ts_real_legal makes one upstream call per day, so ask for few days. Days with no data are listed under unavailable_dates.bourse, farabourse, rights and bonds. Only instruments that traded today are ranked.ins_code.TSETMC has no documented public API. tsetmc-mcp is an unofficial MCP server with 8 read-only tools that calls the
same endpoints the tsetmc.com web app uses and returns compact JSON for AI agents.
Yes. ts_market_movers accepts market="farabourse", and ts_search_symbols finds Fara Bourse instruments;
each match shows its market.
Add the server with claude mcp add tsetmc -- uvx tsetmc-mcp, or use the matching config in
Quick start, then ask in plain language, in Persian or English.
Rial. Every tool reports unit: "rial" where it returns prices. Divide by 10 for Toman.
The order book is only open while the market is. TSETMC trades Saturday to Wednesday mornings; after the close, or
for an instrument that did not trade today, ts_order_book returns no levels and a note.
tsetmc.com blocks some networks. Try from an Iranian connection, or set TSETMC_MCP_PROXY to an HTTP proxy with an
Iranian exit. Plain curl is always refused because the site checks the TLS fingerprint; the server handles that itself.
No. It has no login and no trading calls, it only reads public market data. Nothing it returns is financial advice.
It is what TSETMC serves, kept for up to 15 seconds in a local cache, and it may be delayed. Check the date and
time fields in a quote for the moment of the last trade.
npx @modelcontextprotocol/inspector uvx tsetmc-mcp
| Variable | Default | Meaning |
|---|---|---|
TSETMC_MCP_PROXY | unset | Optional HTTP proxy URL for tsetmc.com 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 |
tsetmc-mcp یک سرور MCP غیررسمی و فقطخواندنی برای سامانه TSETMC (مدیریت فناوری بورس تهران) است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد قیمت نماد، شاخص کل، دفتر سفارش و آمار معاملات بورس تهران و فرابورس را بخواند.
چه کارهایی میکند
نکتهها
TSETMC_MCP_PROXY را روی یک پراکسی HTTP با خروجی ایران بگذارید.نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add tsetmc -- uvx tsetmc-mcp
در Claude Desktop، Cursor و بقیه برنامهها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسشها
git clone https://github.com/sepehr071/tsetmc-mcp && cd tsetmc-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q # offline unit tests
uv run python -m pytest -m live -q # calls tsetmc.com
uv build
All tools live in src/tsetmc_mcp/markets.py; each is a typed async function with a docstring that tells the agent
when to use it. Issues and PRs are welcome.
Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions publishes to PyPI.
Unofficial and not affiliated with or endorsed by TSETMC or the Tehran Securities Exchange Technology Management Co. It is read-only and uses the endpoints of the tsetmc.com web app, which can change without notice. Data is informational and may be delayed. Nothing here is financial advice.
FAQs
Unofficial read-only MCP server for the Tehran Stock Exchange (tsetmc.com): quotes, market movers, order book, history, indices.
We found that tsetmc-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.