msmahdinejad/iran-bourse-mcp

An open-source MCP server that gives any AI agent complete, clean Tehran Stock Exchange (TSETMC / بورس تهران و فرابورس) and Codal data: a stock screener with its own filter language, quotes, order book and queues, tick-by-tick trades, real-vs-legal money flow, options and futures, index history, funds, major shareholders, filings and more. Units are explicit, derived numbers are labelled, and nothing can place an order.
> Unofficial. Not affiliated with TSETMC, the Tehran Stock Exchange, Fara Bourse or Codal. Information only, not investment advice.
▶ 15-second tour (MP4) · GIF for sharing
## Why it exists
An agent with a web browser cannot really read the Iranian market. We tested it:
The site is an empty shell. Fetching a symbol page from tsetmc.com returns a title and nothing else. Codal's report list comes back as unrendered {{template}} placeholders.
The hidden JSON API speaks in codes and has traps. Fields like qTotTran5J, pMeDem, zOrdMeOf; the exchange's own priceChange was 0.0 for a stock that rose 120 rial; order-book history is a delta feed; shareholder rows come back twice.
A day of ticks is 3 MB of JSON. Nobody should paste that into a context window.
iran-bourse-mcp finds the data, fixes the traps, reassembles what is fragmented, summarises what is huge and labels everything it infers.
## Install
Works with every MCP client, and with agents that have none. You need uv (powershell -c "irm https://astral.sh/uv/install.ps1 | iex" or curl -LsSf https://astral.sh/uv/install.sh | sh) and a machine in Iran (why).
bash
# 1. check that TSETMC and Codal are reachable from here
uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp doctor
# 2. print the exact steps for your agent, or let the tool edit the config for you
uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp config cursor
uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp install cursor
The server entry is always the same: command uvx, args ["--from", "git+https://github.com/msmahdinejad/iran-bourse-mcp", "iran-bourse-mcp"], stdio transport. One-click install buttons for Cursor, VS Code and Goose are on the website. An AI agent can set it up from docs/llms-install.md.
All agents and IDEs: copy-paste recipes (17)
#### Claude Code
bash
claude mcp add iran-bourse -- uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp
> Add --scope user to make it available in every project.
#### Claude Desktop
Add to the config file (Windows: %APPDATA%/Claude/claudedesktopconfig.json; macOS: ~/Library/Application Support/Claude/claudedesktopconfig.json; Linux: ~/.config/Claude/claudedesktopconfig.json):
json
"mcpServers": {
"iran-bourse": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/msmahdinejad/iran-bourse-mcp",
"iran-bourse-mcp"
Or automatically (makes a backup first): iran-bourse-mcp install claude-desktop
> Restart Claude Desktop after editing the file.
#### OpenAI Codex CLI
bash
codex mcp add iran-bourse -- uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp
or in ~/.codex/config.toml:
toml
[mcpservers.iran-bourse]