SkillAgentSearch skills...

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-mcp

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

84/100

Supported Platforms

Claude Code
Claude Desktop
Cursor
GitHub Copilot

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.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
4/20
Freshness
15/15

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 found

Our 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.

SkillScoreStarsUpdatedFormat
tsetmc-mcp (this skill)by sepehr07184104d agoMCP Server
Agent-Reachby Panniantong100114.0ktodayCLAUDE.md
hyperframesby heygen-com10088.2ktodayCLAUDE.md
rufloby ruvnet10082.3ktodayCLAUDE.md
headroomby headroomlabs-ai10080.5ktodayCLAUDE.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.
<!-- mcp-name: io.github.sepehr071/tsetmc-mcp --> <div align="center"> <img src="https://raw.githubusercontent.com/sepehr071/tsetmc-mcp/main/.github/banner.png" alt="tsetmc-mcp: unofficial TSETMC MCP server for Claude, Cursor and Copilot" width="100%">

tsetmc-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.

PyPI Python CI MCP Registry License: PolyForm Noncommercial mcpfarsi

Install in VS Code

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-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?"
  • <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).

</details> <details> <summary><b>VS Code (Copilot agent mode)</b></summary>

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.

</details> <details> <summary><b>Anything else</b></summary>

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

</details>

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.
  • 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

<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.

</details> <details> <summary><b>Does it cover Fara Bourse (فرابورس) too?</b></summary>

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

</details> <details> <summary><b>How do I use it with Claude, Cursor or Copilot?</b></summary>

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.

</details> <details> <summary><b>Are prices in Rial or Toman?</b></summary>

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

</details> <details> <summary><b>Why is the order book empty?</b></summary>

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.

</details> <details> <summary><b>I get HTTP 403. What now?</b></summary>

tsetmc.com blocks some networks. Try from an Iranian connection, or set TSETMC_MCP_PROXY to an HTTP proxy with an Iranian exit.

</details> <details> <summary><b>Can it place orders or give investment advice?</b></summary>

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

View on GitHub
GitHub Stars10
CategoryFinance
Updated4d ago
Forks2

Languages

Python

Trust signals

85/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium1 info