iran-bourse-mcp 0.4.0

Website · Install · Benchmarks · Tools · Screener · Real examples · Data notes · راهنمای فارسی · فارسی

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.

▶ Watch the 2-minute film · Download MP4 (22.4 MB) · Vertical 9:16, Full HD and 4K

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

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

claude mcp add iran-bourse -- uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp

{
  "mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

codex mcp add iran-bourse -- uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp

[mcp_servers.iran-bourse]
command = "uvx"
args = ["--from", "git+https://github.com/msmahdinejad/iran-bourse-mcp", "iran-bourse-mcp"]

{
  "mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "servers": {
    "iran-bourse": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "context_servers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

{
  "mcp": {
    "iran-bourse": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ],
      "enabled": true
    }
  }
}

uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp

{
  "amp.mcpServers": {
    "iran-bourse": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msmahdinejad/iran-bourse-mcp",
        "iran-bourse-mcp"
      ]
    }
  }
}

from agents import Agent
from agents.mcp import MCPServerStdio

async with MCPServerStdio(params={"command": "uvx", "args": ["--from", "git+https://github.com/msmahdinejad/iran-bourse-mcp", "iran-bourse-mcp"]}) as bourse:
    agent = Agent(name="Analyst", instructions="Answer with exchange data.", mcp_servers=[bourse])

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "iran-bourse": {"transport": "stdio", "command": "uvx", "args": ["--from", "git+https://github.com/msmahdinejad/iran-bourse-mcp", "iran-bourse-mcp"]}
})
tools = await client.get_tools()

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(mcp_servers={"iran-bourse": {"command": "uvx", "args": ["--from", "git+https://github.com/msmahdinejad/iran-bourse-mcp", "iran-bourse-mcp"]}})

# Any agent that can run commands can use every tool:
uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp tools
uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp call quote symbol=فولاد --compact
uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp call top_movers kind=buy_queue limit=5 --compact

What you can ask

«وضعیت فولاد رو کامل بررسی کن: صف، ورود پول حقیقی، سهامداران عمده و آخرین اطلاعیه‌های کدال» «امروز کدوم سهم‌ها صف خرید قوی دارن و پول حقیقی وارد شده؟» «ریز معاملات فولاد دیروز رو خلاصه کن و بزرگ‌ترین معامله‌ها رو نشون بده» «صف خرید خودرو از چه ساعتی شکل گرفت و چقدر بزرگ شد؟» «سهامدار عمده شستا چه سهم‌های دیگه‌ای داره؟» «سهم‌هایی رو پیدا کن که امروز حجمشون بیش از دو برابر میانگین ۲۰ روز بوده، دیروز بیش از ۱٪ رشد کرده و امروز هم مثبته» ← اسکرینر «زنجیره اختیار معامله اهرم رو با نزدیک‌ترین سررسید بده» · «تاریخچه شاخص کل از اول مهر» · «افزایش سرمایه‌های هفته آینده کدوم نمادهاست؟»

The stock screener

screen_stocks is the filter box of tsetmc.com, written by your agent. Describe what you want; the agent writes a short condition and gets back only the stocks that pass it, with the evidence for each hit. It reads today's live values, up to 60 past trading days (adjusted for capital increases), real-vs-legal flow and a five-level order book for every instrument of the exchange's own market watch (about 3,700, including funds, bonds, options and futures).

You:    stocks trading over twice their 20-day average volume, up more than 1% yesterday, positive today, over 5 billion rial
Agent:  screen_stocks(filter="volume > 2 * avg(volume, 20) and close_pct[1] > 1 and close_pct > 0 and value > 5B")
        35 of 625 stocks match, 3.6 s: انتخاب (9.4x volume, +2.97% yesterday, +2.85% today), پکرمان, کرماشا, خراسان ...

The language is a safe expression grammar (parsed with ast, never eval), accepts the field names and JavaScript spellings of the exchange's own filter (pl, pc, tvol, tmax, pd1, ct.Buy_I_Volume, ===), ships 15 ready-made presets (volume_surge, smart_money, breakout_20d, buy_queue ...) and reports mistakes with suggestions. Checked against an independent re-implementation straight from raw exchange data: identical results on three different screens. Guide and every field: docs/SCREENER.md.

Coverage

Also four prompts (analyze_symbol, daily_market_report, smart_money_scan, find_stocks) and a glossary resource. Full parameters: docs/TOOLS.md.

Benchmarks

Measured against the live exchange, not claimed. The raw route is the best case for an agent that already knows the hidden endpoints. Scripts, ground truth and raw results live in benchmarks/ and can be re-run.

Data-plane benchmark, 2026-11-04 15:51:55 UTC. Tokens are a tiktoken o200k_base proxy; the ratios matter more than the absolute numbers. A single-endpoint task takes about as long either way; the server wins where the raw route needs many sequential requests, and on tokens everywhere.

Traps in the raw data (each found on the live endpoints and handled by the server):

Agent trials (one LLM agent model, identical in every arm, 2026-11-04; 6 tasks, graded against independent ground truth):

Six tasks, one model, runs per task: 1 (2 for T2 and T6 in the shell and MCP arms). The shell agent used its own knowledge of the exchange's endpoints. On T4 it classified a fixed-price symbol (فولاد3) as an ordinary share, a different but defensible reading of 'ordinary shares'; queue sizes also drift by tens of percent within minutes after the close, so T4 is graded on the ranking only.

Verified, not assumed

• Ticks are complete. For فولاد the 6,819 ticks of 3 Nov and the 15,643 ticks of 2 Nov matched the exchange's own daily totals at 100.0% of volume and trade count. trade_summary reports this coverage on every call so you do not have to trust us. (A community reference claimed a 36-38% shortfall; we could not reproduce that.)
• Price limits and queues come from the day's actual allowed price range, not a guess, and queue rankings are confirmed against the real order book.
• Derived numbers are labelled. Anything the exchange does not publish (tick-rule pressure, adjusted prices, same-day value of real money flow) sits under an estimate/estimated key.
• Tested. Offline tests on recorded real fixtures (CI: Python 3.10 to 3.13 on both MCP SDK generations), a live smoke test of every tool (scripts/smoke_live.py) and an end-to-end stdio test (scripts/e2e_stdio.py).

Architecture

Pure transformation logic (shape.py) is separated from I/O so every number can be tested offline. Details: docs/ARCHITECTURE.md (فارسی).

The Iranian IP requirement

TSETMC and Codal are built for Iranian users. Their servers often reject foreign or VPN addresses. So:

• Run the server on a machine in Iran, not behind a foreign VPN, or
• point it at an in-Iran proxy: IRAN_BOURSE_PROXY=http://host:port, or
• run it on an Iranian server and connect remotely over HTTP (use an SSH tunnel or a reverse proxy with authentication; the server has no auth of its own):

iran-bourse-mcp serve --transport streamable-http --host 127.0.0.1 --port 8000

iran-bourse-mcp doctor tells you which sources are reachable. A Dockerfile is included (docker build -t iran-bourse-mcp . && docker run -i --rm iran-bourse-mcp); images are pushed to ghcr.io on tagged releases.

Configuration

Good to know

• Prices and values are in Rial (1 Toman = 10 Rial). Dates accept Gregorian (2026-11-03) or Jalali (1405/08/12, Persian digits fine).
• Persian/Arabic letter variants are interchangeable on input (کگل = كگل) and normalised on output.
• The market trades Saturday-Wednesday 09:00-12:30 Tehran time, except on official public holidays. market_status knows the 1405 holiday calendar (holiday, next_session, upcoming_holidays); for years not yet in the table only the fixed Solar Hijri holidays are known. The exchange also closes on some days without a holiday; market_status flags it when the exchange's own data disagrees with the calendar. Outside the session you get the last session's data.
• Order-book history for the current trading day may be partial. TSETMC publishes the full intraday book history only after the day ends. order_book_history tells you when it is cut short (events_span, warning). Use order_book for the live book.
• The unofficial endpoints can change without notice. Every quirk we found is in docs/DATA_SOURCES.md (فارسی).
• Requests are cached briefly (seconds for live data, hours for history) and limited to 6 in flight. Please be gentle: this is somebody else's server.

Troubleshooting

Safety

All tools are read-only (readOnlyHint). There is deliberately no order placement, no login and no credential handling.

Development

uv sync
uv run pytest                           # offline, a few seconds
uv run ruff check .
uv run python scripts/smoke_live.py     # needs access to TSETMC
uv run python scripts/e2e_stdio.py      # real MCP handshake against live data
uv run python benchmarks/data_plane.py  # re-measure tokens, requests, time

See CONTRIBUTING.md, AGENTS.md and docs/ARCHITECTURE.md.

Roadmap

• Holiday table for Jalali year 1406 (once the official calendar is final)
• Published PyPI release (uvx iran-bourse-mcp)

Citing

See CITATION.cff. Licensed under MIT. Market data belongs to its respective owners; check the exchange's terms before redistributing it.