Skip to main content
Glama
tsetmc-mcp

tsetmc-mcp

by sepehr071

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.

PyPI Python CI MCP Registry License: MIT mcpfarsi

Install in VS Code

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.

Related MCP server: fipiran-mcp

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

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.

Tools

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.

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

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

Configuration

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

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

tsetmc-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای سامانه TSETMC (مدیریت فناوری بورس تهران) است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد قیمت نماد، شاخص کل، دفتر سفارش و آمار معاملات بورس تهران و فرابورس را بخواند.

چه کارهایی می‌کند

  • جستجوی نماد سهام، صندوق، حق تقدم و اوراق (با نام یا نماد فارسی؛ «ي» و «ك» عربی هم پذیرفته می‌شود).

  • قیمت لحظه‌ای نماد: آخرین معامله، قیمت پایانی، بازه روز، حجم، ارزش، بازه مجاز قیمت و ارزش بازار.

  • پرمعامله‌ها و بیشترین رشد و افت در بورس، فرابورس، حق تقدم و اوراق، با نشانه صف خرید یا فروش (قیمت در سقف یا کف مجاز).

  • دفتر سفارش با ۵ سطح بهترین خرید و فروش.

  • تاریخچه روزانه قیمت تا ۵۰ روز معاملاتی (قیمت‌ها تعدیل نشده‌اند).

  • حقیقی و حقوقی: حجم و ارزش خرید و فروش و تعداد خریدار و فروشنده به تفکیک حقیقی و حقوقی، تا ۱۰ روز.

  • شاخص‌ها: شاخص کل، شاخص هم‌وزن، وضعیت بازار و شاخص همه صنعت‌ها، و تاریخچه تا ۱۰۰ روز.

نکته‌ها

  • فقط خواندنی است: وارد حساب نمی‌شود و سفارش ثبت نمی‌کند. توصیه سرمایه‌گذاری نیست.

  • قیمت‌ها به ریال است؛ برای تومان تقسیم بر ۱۰ کنید. تاریخ‌ها میلادی هستند.

  • بازار شنبه تا چهارشنبه، صبح‌ها باز است؛ بعد از بسته شدن بازار دفتر سفارش خالی است.

  • اگر سایت خطای ۴۰۳ داد، از اینترنت ایران استفاده کنید یا متغیر TSETMC_MCP_PROXY را روی یک پراکسی HTTP با خروجی ایران بگذارید.

  • کلید API لازم نیست و روی سیستم خود شما اجرا می‌شود.

نصب (اول uv را نصب کنید). در Claude Code:

claude mcp add tsetmc -- uvx tsetmc-mcp

در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.

نمونه پرسش‌ها

  • «شاخص کل امروز چقدر تغییر کرده و کدام صنعت‌ها جلوتر هستند؟»

  • «دفتر سفارش فولاد را نشان بده.»

  • «پرمعامله‌ترین نمادهای فرابورس امروز کدام‌اند؟»

  • «ورود و خروج پول حقیقی وبملت در ۵ روز اخیر چطور بوده؟»

  • «تاریخچه ۳۰ روزه شاخص کل را بده.»

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.

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.

Author

Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp. If this saves you time, a star on the repo helps other people find it.

License

MIT

Available Tools

8 tools
ts_get_quoteStock quoteA
Read-onlyIdempotent

Latest price, daily range, volume and key facts of one instrument on the Tehran Stock Exchange.

Use ts_order_book for bids and asks, ts_price_history for earlier days.

Inputs: symbol (required).

ts_index_historyIndex historyA
Read-onlyIdempotent

Daily close, high, low and percent change of a TSE index (total, equal-weight, sector...), newest first.

Names: see ts_indices.

Inputs: days, index.

ts_indicesMarket indicesA
Read-onlyIdempotent

TSE total index, market state and trading totals, plus every sector and market index with its change.

Pass an index name to ts_index_history for past values.

Inputs: limit, query.

ts_market_moversMarket moversA
Read-onlyIdempotent

Top traded instruments of a market today, ranked by gain, loss, volume, value or trade count.

Only traded instruments. limit_up/limit_down = stuck at the daily limit. Pass a row's symbol to other ts_ tools.

Inputs: limit, market, sort_by.

ts_order_bookOrder bookA
Read-onlyIdempotent

Best five bid and ask levels (price, volume, order count) of one instrument.

Empty outside trading hours. Ask price 0 = buy queue (no sellers), bid price 0 = sell queue.

Inputs: symbol (required).

ts_price_historyDaily price historyA
Read-onlyIdempotent

Daily open, high, low, close, volume, trades and value of one instrument for its latest trading days, newest first.

Prices are unadjusted for capital increases and dividends.

Inputs: symbol (required), days.

ts_search_symbolsSearch symbolsA
Read-onlyIdempotent

Find Tehran Stock Exchange instruments (shares, funds, rights, bonds) by ticker or name.

Pass a result's symbol or ins_code to the other ts_ tools. Empty list: retry a shorter name.

Inputs: query (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct data shape: symbol search, single-instrument quote, market-wide movers, order book depth, daily price history, real/legal flow split, index listing, and index history. Descriptions actively cross-reference siblings (e.g. 'Use ts_order_book for bids and asks, ts_price_history for earlier days'), leaving no realistic misselection path.

    Naming Consistency4/5

    All names share a uniform ts_ prefix and snake_case, but the pattern is mixed: some are verb_noun (ts_search_symbols, ts_get_quote) while most are noun-only (ts_order_book, ts_price_history, ts_indices). Readable and predictable in practice, just not a single strict convention.

    Tool Count5/5

    Eight tools is well-scoped for a read-only exchange data server, with one tool per data type and no filler. Nothing feels redundant or missing at the count level.

    Completeness4/5

    The surface covers the core read paths: discovery, snapshot, movers, depth, history, flow composition, and indices with history. Minor gaps remain (no sector/index constituent lookup, no adjusted-price option, no market-wide snapshot beyond movers), but agents can work around these via search plus quote.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search and read Iranian listed companies’ Codal disclosures, including financial statements, EPS and monthly activity reports as tables, meeting decisions, and PDF/Excel links, plus company and fiscal-year lookups.
      5
      332 PyPI
      9
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search, rank, and compare Iranian mutual funds and ETFs; inspect NAV, returns, size, flows, investors, and managers; and retrieve Tehran and Farabourse market overviews, indices, stock quotes, and industry data read-only without an API key.
      11
      99 PyPI
      PolyForm Noncommercial 1.0.0
    • A
      license
      A
      quality
      B
      maintenance
      Gives AI agents read-only access to the public trade and supply data of the Iran Mercantile Exchange, covering commodity trades, upcoming supply offers, daily price series, market totals, options, certificates, rankings, news and weekly reports. Requires no API key or account, and works in Claude, Cursor, Copilot and any other MCP client.
      14
      99 PyPI
      PolyForm Noncommercial 1.0.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to query public Iran Fara Bourse data read-only, including bond, sukuk and treasury bill yields, instrument and coupon details, live quotes and order books, IPOs, announcements, news and market statistics.
      16
      100 PyPI
      MIT