Model Context Protocol · open source · MIT
40 read-only tools that hand any agent the quotes, order book, tick-by-tick trades, real vs legal money flow, shareholders, a stock screener, options, indices, funds and Codal filings of TSETMC. Clean, labelled, and ready to reason about.
$uvx iran-bourse-mcp doctor
Launch film, 2 min
Real answers from the real server: a buy queue in one call, every Foolad trade of a single minute, and a market-wide screen that costs about 10,000 times fewer tokens.
Every number on screen is real tool output captured on 4 Nov 2026, with the market closed. The benchmark is small and single-model.
Free to download and share.
The problem
We tested it. The market's data exists, but it is hidden behind JavaScript, written in codes, and shipped in megabytes.
Fetching a symbol page from tsetmc.com returns a title and nothing else. Codal's report list comes back as unrendered template placeholders.
GET tsetmc.com/instInfo/4634… → ".:TSETMC:. :: مدیریت فناوری بورس تهران" GET codal.ir/ReportList.aspx → {{::letter.Title}} {{::letter.PublishDateTime}}
The JSON endpoints that hold the data use cryptic names and have traps. The exchange's own change field said zero for a stock that rose 120 rial.
"qTotTran5J": 646253701, "pMeDem": 4210, "zOrdMeOf": 7, "priceChange": 0.0, "pClosing": 4210, "priceYesterday": 4090
Order-book history is a delta feed that must be reassembled, shareholder rows come back twice, and a symbol's messages weigh 3.5 MB. None of it fits a context window.
Trade/GetTradeHistory 3.1 MB BestLimits/{ins}/{day} 3.3 MB Msg/GetMsgByInsCode 3.5 MB GetClosingPriceDailyList 1.5 MB
Same question, two agents
Outputs shown are real, captured on 2026-11-03. The browser-only agent cannot even find the data; an agent that guesses the hidden endpoint can be misled by their fields.
New: stock screener
Say what you want in plain words. The agent writes a short condition and gets back only the stocks that pass it right now, with the evidence for each hit.
Live values, yesterday (close[1]), averages (avg(volume, 20)), streaks (all(close_pct > 0, 3)) and highs over any window, adjusted for capital increases.
Shares, funds, bonds, options and futures from the exchange's own feed, with real vs legal flow, a five-level book, base volume and fund NAV.
Conditions are parsed, never executed. Mistakes come back with suggestions, 15 presets are built in, and every hit shows the numbers behind it.
Measured, not claimed
Eight everyday tasks, run against the live exchange. The raw route is the best case for an agent that already knows the hidden endpoints.
Log scale. Raw JSON payload vs the MCP response.
Seconds, sequential raw requests vs one tool call.
Log scale. MCP always needs one call.
Each one was found on the live endpoints and is handled by the server.
Install
One server, every client that speaks MCP. Pick yours below, or use the shell command if your agent has no MCP support.
uv runs the server without a manual install.
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"curl -LsSf https://astral.sh/uv/install.sh | shFrom a machine in Iran, confirm TSETMC and Codal answer.
uvx iran-bourse-mcp doctorChoose your agent. Some have a one-click link or an auto-installer.
uvx iran-bourse-mcp configAsk in Persian
40 tools
Every tool is read-only, returns units explicitly, and labels anything it derives.
How it works
Transformation logic is separate from I/O, so every number can be tested offline against recorded real data. Facts are returned as published; derived numbers are labelled.
Built to be trusted
FAQ
Free, open source, read-only. Star it if it saves you an afternoon.
$claude mcp add iran-bourse -- uvx iran-bourse-mcp