tsetmc-mcp
A read-only MCP server that gives AI agents access to Tehran Stock Exchange and Iran Fara Bourse market data.
Search instruments – find shares, funds, rights issues and bonds by Persian ticker or name (
ts_search_symbols)Get a quote – last trade, closing price, daily range, volume, value, allowed price range, market cap (
ts_get_quote)Rank movers – top gainers, losers, volume, value or trade count across bourse, farabourse, rights and bonds, with limit-up/down flags (
ts_market_movers)Read the order book – best five bid/ask levels with price, volume and order count, incl. buy/sell queues (
ts_order_book)Pull daily history – OHLC, volume, trades and value for up to 50 trading days (
ts_price_history)Track real vs legal flow – individual vs institutional buy/sell volume, value and counts, plus net real volume (
ts_real_legal)Scan indices – total, equal-weight and sector indices with changes (
ts_indices), plus up to 100 days of any index's history (ts_index_history)
All tools are read-only (no login, no orders), return compact JSON in Rial with Gregorian dates, and need no API key.
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 what are today's top gainers on the Tehran Stock Exchange?"
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: 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-mcporclaude 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, callts_search_symbolsfirst and pass itssymbolorins_codeto 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.jsonand 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-mcpSettings → 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-mcpOr 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 |
| Find Tehran Stock Exchange instruments (shares, funds, rights, bonds) by ticker or name |
| Latest price, daily range, volume and key facts of one instrument on the Tehran Stock Exchange |
| Top traded instruments of a market today, ranked by gain, loss, volume, value or trade count |
| Best five bid and ask levels (price, volume, order count) of one instrument |
| Daily open, high, low, close, volume, trades and value of one instrument for its latest trading days, newest first |
| Buy and sell volume, value and buyer/seller counts split by real (individual) and legal (institutional) traders per day |
| TSE total index, market state and trading totals, plus every sector and market index with its change |
| 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, indicestsetmc-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.
lastvsclose:lastis the last trade,closethe closing (volume-weighted) price;change_pctcompareslastwith 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_PROXYto an HTTP proxy with an Iranian exit. System proxy variables are ignored on purpose.Reply caps:
ts_market_moversreturns at most 30 rows,ts_price_history50 days,ts_index_history100 days,ts_real_legal10 days,ts_indices60 indices.ts_real_legalmakes one upstream call per day, so ask for few days. Days with no data are listed underunavailable_dates.Movers cover four markets:
bourse,farabourse,rightsandbonds. 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-mcpConfiguration
Variable | Default | Meaning |
| 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 buildAll 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
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
Listed on mcpfarsi.ir, the Persian MCP marketplace
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
Available Tools
8 toolsts_get_quoteStock quoteARead-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 historyARead-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 indicesARead-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 moversARead-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 bookARead-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 historyARead-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_real_legalReal vs legal tradingARead-onlyIdempotent
Buy and sell volume, value and buyer/seller counts split by real (individual) and legal (institutional) traders per day.
net_real_volume > 0: individuals net bought. Newest day first.
Inputs: symbol (required), days.
ts_search_symbolsSearch symbolsARead-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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Live crypto + IDX stock market intelligence for AI agents — 19 tools, no API key.
Licensed Borsa Istanbul (BIST) data for AI assistants: live or 15-minute delayed prices, OHLCV bars from 1 minute to monthly, financial statements, ratios, KAP disclosures, indices and sectors, indicator backtests and portfolio tracking for 600+ Turkish stocks. OAuth sign-in with an istfin subscription. Never places orders.
Live stock quotes, a stock screener, crypto prices and FX rates as agent tools.
US stock market data for AI agents: SEC filings, financials, insider trades, 13F, options, macro.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables 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.5332 PyPI9MIT
- AlicenseAqualityBmaintenanceEnables 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.1199 PyPIPolyForm Noncommercial 1.0.0
- AlicenseAqualityBmaintenanceGives 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.1499 PyPIPolyForm Noncommercial 1.0.0
- AlicenseAqualityBmaintenanceEnables 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.16100 PyPIMIT