tsetmc-mcp
Unofficial read-only MCP server for the Tehran Stock Exchange (TSETMC) and Iran Fara Bourse: stock quotes, top movers, order book, price history, indices, real vs legal trading. For Claude, Cursor and Copilot. بورس تهران
Install / Use
claude mcp add sepehr071 -- npx -y github:sepehr071/tsetmc-mcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Finance & AccountingSupported Platforms
Our assessment of tsetmc-mcp
tsetmc-mcp scores 84/100 on our quality scale, 66th of 108 Finance & Accounting skills we index.
Its MCP Server is 18 KB long, well organised into 15 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 4 days ago, so tsetmc-mcp is actively maintained.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 85/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.
Automated pattern scan on 2026-11-21. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
tsetmc-mcp compared with similar skills
All 4 of these similar skills score higher than tsetmc-mcp; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| tsetmc-mcp (this skill)by sepehr071 | 84 | 10 | 4d ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 80.5k | today | CLAUDE.md |
Frequently asked questions
- How do I install tsetmc-mcp?
- Run
claude mcp add sepehr071 -- npx -y github:sepehr071/tsetmc-mcp. The install tabs above show the steps for each supported agent. - Which AI agents does tsetmc-mcp work with?
- It is written for Claude Code, Claude Desktop, Cursor and GitHub Copilot, as a MCP Server file. Other agents that read the same format can often use it too.
- Is tsetmc-mcp safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It declares no license and scores 85/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is tsetmc-mcp still maintained?
- The repository was last updated 4 days ago, so tsetmc-mcp is actively maintained.
Skill content
View source on GitHubtsetmc-mcp: Tehran Stock Exchange MCP server for AI agents
Let your AI agent read the Tehran Stock Exchange (بورس تهران).<br> An unofficial, read-only MCP server for TSETMC, the data portal of the Tehran Stock Exchange and Iran Fara Bourse:<br> 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 · فارسی
</div>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.
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?"
- <span dir="rtl">شاخص کل امروز چقدر تغییر کرده و کدام صنعتها بیشترین رشد را داشتند؟</span>
- <span dir="rtl">ورود و خروج پول حقیقی فولاد در سه روز اخیر چطور بوده؟</span>
- <span dir="rtl">بیشترین حجم معاملات امروز فرابورس مربوط به کدام نمادهاست؟</span>
Quick start
You need uv. No API key or account.
<details open> <summary><b>Claude Code</b></summary>claude mcp add tsetmc -- uvx tsetmc-mcp
</details>
<details>
<summary><b>Claude Desktop</b></summary>
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"tsetmc": { "command": "uvx", "args": ["tsetmc-mcp"] }
}
}
</details>
<details>
<summary><b>Cursor</b></summary>
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"] }
}
}
</details>
<details>
<summary><b>Codex CLI</b></summary>
codex mcp add tsetmc -- uvx tsetmc-mcp
Or in ~/.codex/config.toml:
[mcp_servers.tsetmc]
command = "uvx"
args = ["tsetmc-mcp"]
</details>
<details>
<summary><b>Gemini CLI</b></summary>
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"tsetmc": { "command": "uvx", "args": ["tsetmc-mcp"] }
}
}
</details>
<details>
<summary><b>Windsurf</b></summary>
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.
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
<details> <summary><b>Is there a TSETMC API or Tehran Stock Exchange MCP server?</b></summary>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.
No. It has no login and no trading calls, it only reads public market data. Nothing it returns is financial advice.
</details> <details> <summary><b>Is the data real time?</b></summary>It is what TSETMC serves, kept for up to 15 seconds in a local cache, and it may be delayed
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
80.5kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
