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 awesome-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 mcp add tsetmc -- uvx tsetmc-mcp

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

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

codex mcp add tsetmc -- uvx tsetmc-mcp

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

{
  "mcpServers": {
    "tsetmc": { "command": "uvx", "args": ["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

npx @modelcontextprotocol/inspector uvx tsetmc-mcp

Configuration

فارسی: سرور MCP بورس تهران (TSETMC)

claude mcp add tsetmc -- uvx tsetmc-mcp

Development

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.

Related servers

• awesome-iran-mcp: catalog of all Iranian-service MCP servers
• tgju-mcp for dollar, gold, coin and commodity prices from TGJU
• iran-crypto-mcp for crypto prices on Iranian exchanges
• milligold-mcp for gold prices on Milli
• iran-news-mcp for Iranian news

Disclaimer

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.

License

MIT