TSETMC Tehran Stock Exchange

tsetmc-mcp: Tehran Stock Exchange MCP server for AI agents

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 · فارسی

---

For AI agents

• What: unofficial MCP server (model context protocol) for tsetmc.com, the Tehran Stock Exchange and Iran Fara Bourse market data. Symbol search takes Persian names (Arabic ي/ك are accepted).
• Install: uvx tsetmc-mcp or claude mcp add tsetmc -- uvx tsetmc-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account. Optional TSETMC_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
• Access: read-only. It cannot log in, trade or place orders, so no confirmation is needed before calling any tool.
• Tools: 8, all prefixed 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.
• Use when: the user asks about Tehran Stock Exchange or Fara Bourse prices, movers, sector indices, order book or real vs legal money flow.
• Do not use when: the user wants to trade, needs fundamentals or Codal filings, or asks about other exchanges.
• Output: compact JSON. Prices in Rial (Toman = Rial / 10), volumes in shares, dates Gregorian (YYYY-MM-DD).
• Network: tsetmc.com answers only some networks. On HTTP 403, try an Iranian connection or set TSETMC_MCP_PROXY.
• Machine-readable: server.json and the iran-mcp catalog.

Why

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.

What it can do

• Look up any share, fund, rights issue or bond on the Tehran Stock Exchange or Iran Fara Bourse by ticker or name
• Quote one instrument: last trade, closing price, daily range, volume, trades, value, allowed price range, week and year range, shares outstanding and market cap
• Rank movers of Bourse, Fara Bourse, rights or bonds by gain, loss, volume, value or trade count, with a flag for prices at the daily limit
• Read the order book: best five bid and ask levels with price, volume and order count, including buy and sell queues
• Pull daily history: open, high, low, close, volume, trades and value for up to 50 trading days
• Track real vs legal trading (حقیقی و حقوقی): buy and sell volume, value and counts per day, plus net individual volume
• Scan indices: the total index, equal-weight index, market state and every sector index, and up to 100 days of any index's history
• Read-only by design: no login, no orders

Example prompts:

• "Which TSE sectors are leading today?"
• "Top 10 Fara Bourse stocks by traded value."
• "Show the order book for فولاد."
• "Last 20 trading days of وبملت, and did individual investors buy or sell over the last 3 days?"
• "How has the total index moved over the last 30 days?"
• شاخص کل امروز چقدر تغییر کرده و کدام صنعت‌ها بیشترین رشد را داشتند؟
• ورود و خروج پول حقیقی فولاد در سه روز اخیر چطور بوده؟
• بیشترین حجم معاملات امروز فرابورس مربوط به کدام نمادهاست؟

Quick start

You need uv. No API key or account.

Claude Code

claude mcp add tsetmc -- uvx tsetmc-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

{

"mcpServers": { "tsetmc": { "command": "uvx", "args": ["tsetmc-mcp"] } } }

</details>

Cursor

Add the Claude Desktop block above to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

VS Code (Copilot agent mode)

Click Install in VS Code above, or add to .vscode/mcp.json:

{

"servers": { "tsetmc": { "type": "stdio", "command": "uvx", "args": ["tsetmc-mcp"] } } }

</details>

Codex CLI

codex mcp add tsetmc -- uvx tsetmc-mcp

Or in ~/.codex/config.toml:

[mcp_servers.tsetmc]

command = "uvx" args = ["tsetmc-mcp"]

</details>

Gemini CLI

Add to ~/.gemini/settings.json:

{

"mcpServers": { "tsetmc": { "command": "uvx", "args": ["tsetmc-mcp"] } } }

</details>

Windsurf

Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.

Anything else

It is a standard stdio MCP server: run uvx tsetmc-mcp, or pip install tsetmc-mcp and run tsetmc-mcp.

Tools

Pass a ticker (فولاد), an exact name, or a numeric ins_code as symbol. Index tools take an index name such as شاخص کل.

All 8 tools are annotated readOnlyHint: true.

How it works

  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.

Good to know

• Prices are in Rial, as TSETMC quotes them. Divide by 10 for Toman. Volumes are in shares.
• Prices are not adjusted for capital increases or dividends, so long histories can show jumps.
• `last` vs `close`: last is the last trade, close the closing (volume-weighted) price; change_pct compares last with yesterday's close.
• Trading hours: the market trades Saturday to Wednesday, in the morning. Outside those hours the order book is empty and other tools show the last session.
• Network: tsetmc.com blocks some networks with HTTP 403. It worked from an Iranian line; a foreign exit may or may not be accepted. If you get 403, set TSETMC_MCP_PROXY to an HTTP proxy with an Iranian exit. System proxy variables are ignored on purpose.
• Reply caps: 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.
• Movers cover four markets: bourse, farabourse, rights and bonds. Only instruments that traded today are ranked.
• Names: Arabic ي/ك and Persian ی/ک both match, and answers use the Persian forms. An ambiguous name returns an error listing candidates; pass the exact ticker or ins_code.
• What it does not do: no trading or orders, no company fundamentals or Codal filings, no options or futures movers, no adjusted prices, no Jalali dates. Rate limits of TSETMC are unknown, so keep requests reasonable.

FAQ

Is there a TSETMC API or Tehran Stock Exchange MCP server?

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.

Does it cover Fara Bourse (فرابورس) too?

Yes. ts_market_movers accepts market="farabourse", and ts_search_symbols finds Fara Bourse instruments; each match shows its market.

How do I use it with Claude, Cursor or Copilot?

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.

Are prices in Rial or Toman?

Rial. Every tool reports unit: "rial" where it returns prices. Divide by 10 for Toman.

Why is the order book empty?

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 tra