iran-brokers-mcp: Iranian broker (کارگزاری بورس) market data MCP server for AI agents

iran-brokers-mcp is an unofficial, read-only MCP server that lets an AI agent read Tehran Stock Exchange market data through two Iranian brokers, Mofid Securities (کارگزاری مفید, emofid.com) and Agah (کارگزاری آگاه, agah.com). Its 22 tools cover stocks, ETFs and funds (صندوق سرمایه‌گذاری), options (آپشن), bonds and sukuk (اوراق), gold coins (سکه) and currency, screeners, Codal announcements and education articles, on Tehran Stock Exchange (بورس تهران) and Fara Bourse (فرابورس). No API key or broker account is needed, and it works in Claude, Cursor, Copilot and any other MCP client.

For AI agents · What it can do · Quick start · Tools · Limits · FAQ · فارسی

Last verified 2026-11-01 against the live Mofid and Agah APIs.

For AI agents

• What: unofficial MCP server (model context protocol) for Mofid and Agah: symbol search, stock cards, OHLC candles and daily history, market snapshot, 36 Mofid rankings, Agah market watch and screener, ETFs with price vs NAV, fund detail/history/comparison, options chain and contract, bonds and T-bills, currency/coin/gold/commodity prices and history, Codal filings, valuation scores, technical tally, education articles and courses.

• Install: uvx iran-brokers-mcp or claude mcp add iran-brokers -- uvx iran-brokers-mcp. Transport: stdio. Needs uv (Python 3.10+).

• Auth: none. Optional IRAN_BROKERS_MCP_PROXY (one HTTP proxy URL for every request, or a comma-separated list); system proxy settings are ignored.

• Access: read-only market data. It cannot log in, read a portfolio, cash or orders, place, edit or cancel orders, or pay. No confirmation is needed before calling any tool.

• Tools: 22, all prefixed br_. Typical sequences: br_search -> br_stock / br_history; br_market -> br_market_top or br_stocks; br_etfs -> br_stock or br_fund; br_screener; br_rates; br_announcements; br_learn -> br_learn(ref=...).

• source argument: each source answers in its own block ({"mofid": ..., "agah": ...}). With all, a source that fails shows {"error": ...} and the other still answers. Blocks are never blended into one row, because the fields differ.

• Use when: the user asks for a stock, fund, option, index, gold or dollar price on the Iranian market, a ranking or screen, a chart, a company's Codal filings, or how something in the bourse works.

• Do not use when: the user wants to trade, see their own portfolio, or needs real-time tick data (everything here is a polled snapshot). For raw exchange data use tsetmc-mcp; for full financial statements use codal-mcp.

• Output: compact JSON. Prices are Rial (divide by 10 for Toman). Text Persian.

• Machine-readable: server.json and the iran-mcp catalog.

Related MCP server: codal-mcp

What it can do

• Get Tehran Stock Exchange data in Claude: find a symbol, read its price card (P/E, EPS, NAV, buyer and seller flows, order book), candles from 1 minute to weekly, and the market snapshot with indices and movers

• Compare Iranian ETFs from an AI agent: list ETFs with price, NAV and the bubble gap (Mofid 375 ETFs, Agah 331 listed ETFs), then read one fund's detail, NAV history or compare several

• Read the options chain (call and put contracts) and one contract's detail

• Screen stocks, ETFs or funds on any column with the Agah screener, or use Mofid's 36 rankings (top gainers, value, queues and more)

• Bonds, sukuk and T-bills with yield, plus currency, crypto, coin (سکه), gold and commodity prices with history

• Codal announcements by company, type and date, plus notices, news and research PDFs

• Valuation and technical scores: theoretical price, fundamental and technical scores, indicator tally per stock or industry

• Education: Mofid blog, Agah Pedia articles and Agah Academy courses

• Read-only by design: no login, no orders, no captcha solving

Example prompts:

• "Get today's Tehran Stock Exchange summary: indices, top movers and the dollar and coin prices."

• "Compare Iranian ETFs by price versus NAV and show which trade at the biggest premium."

• "Show the options chain for Foolad and the details of one call contract."

• "Which stocks have the lowest P/E and a positive money flow this week?"

• قیمت و نسبت قیمت به NAV صندوق‌های طلا را مقایسه کن.

• بیشترین صف خرید امروز بورس کدام نمادهاست؟

• آخرین اطلاعیه‌های کدال نماد فولاد را بیاور.

Quick start

You need uv. No API key or account.

claude mcp add iran-brokers -- uvx iran-brokers-mcp

Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "iran-brokers": { "command": "uvx", "args": ["iran-brokers-mcp"] }
  }
}

Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

Click Install in VS Code above, or add to .vscode/mcp.json:

{
  "servers": {
    "iran-brokers": { "type": "stdio", "command": "uvx", "args": ["iran-brokers-mcp"] }
  }
}

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

Tools

Merged tools take source: mofid, agah or all (the default is in brackets). Single-source tools say which broker they use.

Every tool is read-only. If you used the separate mofid-mcp or agah-mcp servers: mf_search and ag_search -> br_search; mf_symbol, mf_depth, ag_stock -> br_stock; mf_history, ag_stock_history -> br_history; mf_market_summary, ag_market_pulse, ag_market_overview -> br_market; mf_industries, ag_industries -> br_industries; mf_index, ag_index_history -> br_index; mf_etfs -> br_etfs; mf_learn, mf_learn_categories, ag_articles, ag_article, ag_academy -> br_learn; mf_fx_gold, mf_rate_history -> br_rates; ag_fund, ag_fund_trend, ag_fund_compare -> br_fund; ag_options, ag_option -> br_options; the others keep their name with the br_ prefix (mf_quote -> br_quotes).

Limits

• No portfolio, orders or cash. Those need a broker login (EasyTrader, AsaTrader); nothing here logs in or can place an order, and this is not built.

• Agah Pedia and Academy answer only from an Iranian network (pediaapi.agah.com, academyapi.agah.com time out from abroad). The error says so; the Mofid side of br_learn still answers. Do not put a foreign proxy in front of them.

• Mofid depends on the accept-info header of the Bourse View gateway (derived from the server clock; the client resyncs on a 401). If the site changes that check, Mofid tools fail with an HTTP 401 error and the Agah side keeps working.

• Data is polled snapshots, cached 30 to 60 seconds, delayed or unaudited; the market trades Saturday to Wednesday about 09:00-12:30 Tehran time.

• The two sources use different ids for funds (Mofid ISIN, Agah 11-digit national code) and different fields, so merged tools show them side by side.

• Prices are Rial; divide by 10 for Toman. Dates follow each site.

FAQ

Add iran-brokers-mcp with claude mcp add iran-brokers -- uvx iran-brokers-mcp, then ask in plain language. The agent finds the symbol with br_search, reads it with br_stock or br_history, and gets the market overview from br_market.

Use br_etfs for the list with price, NAV and gap (bubble), br_fund for one fund's detail, NAV history or a side-by-side comparison, and br_screener to filter funds on any column.

Neither broker documents a public API. This server calls the same public JSON the websites use, without login, and returns compact JSON.

No. It is read-only and has no login. Portfolio, cash and orders need your broker account and are not built.

Yes for Mofid and Agah Research. Agah Pedia and Academy answer only from an Iranian network. Set IRAN_BROKERS_MCP_PROXY to route through a proxy; do not use a foreign one for Pedia and Academy.

It calls the public endpoints the websites use, two requests at a time per broker and with caching, and each client sends the headers its site's web app sends (Chrome TLS fingerprint, Referer, Accept, Mofid's accept-info).

tsetmc-mcp and codal-mcp read the exchange and Codal directly; this server reads the brokers' own views of the same market (rankings, screeners, NAV gaps, options, education).

No to both. Data is polled snapshots cached for 30 to 60 seconds. Nothing it returns is financial advice.

Configuration

فارسی: سرور MCP کارگزاری‌های مفید و آگاه برای دستیار هوش مصنوعی

پروژه iran-brokers-mcp یک سرور MCP غیررسمی و فقط‌خواندنی است که داده‌های عمومی بازار سرمایه را از دو کارگزاری، کارگزاری مفید (emofid.com) و کارگزاری آگاه (agah.com)، در اختیار دستیار هوش مصنوعی (Claude، Cursor، Copilot و ...) می‌گذارد.

چه کارهایی می‌کند

• سهام بورس تهران و فرابورس: جستجوی نماد، کارت قیمت، کندل، تاریخچه روزانه، خلاصه بازار و شاخص‌ها.

• صندوق‌های سرمایه‌گذاری و ETF: قیمت، NAV، حباب، تاریخچه و مقایسه صندوق‌ها.

• اوراق و آپشن: اوراق بدهی، صکوک، اوراق خزانه با بازده؛ زنجیره آپشن و جزئیات هر قرارداد.

• سکه، طلا و ارز: قیمت و تاریخچه.

• غربالگر و رتبه‌بندی: ۳۶ رتبه‌بندی مفید و غربالگر آگاه روی هر ستون.

• اطلاعیه‌های کدال، خبر و آموزش: مقاله‌ها و دوره‌های مفید و آگاه.

نکته‌ها

• فقط‌خواندنی است: ورود به حساب، سبد دارایی، موجودی و ثبت سفارش ندارد.

• پدیا و آکادمی آگاه فقط از اینترنت ایران جواب می‌دهد.

• داده‌ها لحظه‌ای نیست و هر ۳۰ تا ۶۰ ثانیه تازه می‌شود. مبلغ‌ها ریال است. توصیه سرمایه‌گذاری نیست.

• کلید API لازم نیست و سرور روی سیستم خود شما اجرا می‌شود.

نصب (اول uv را نصب کنید). در Claude Code:

claude mcp add iran-brokers -- uvx iran-brokers-mcp

Development

git clone https://github.com/sepehr071/iran-brokers-mcp && cd iran-brokers-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q          # offline unit tests on recorded responses
uv run python -m pytest -m live -q  # live pass against Mofid and Agah
uv build

Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions publishes to PyPI. Issues and PRs are welcome.

Related servers

• tsetmc-mcp for Tehran Stock Exchange prices, order book, real vs legal trading and indices

• codal-mcp for Codal disclosures and financial statements

• iran-gold-mcp for live 18k gold prices on Iranian platforms

• iran-mcp: catalog of all Iranian-service MCP servers

Disclaimer

Unofficial and not affiliated with or endorsed by Mofid Securities or Agah. It is read-only and uses the public endpoints of their websites, which can change without notice. Data is informational, delayed and unaudited. Nothing here is investment advice.

Author

Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp. If this saves you time, a star on the repo helps other people find it.

License

MIT