codal-mcp: Codal (کدال) disclosure and financial statement MCP server for AI agents

codal-mcp lets an AI agent search and read Codal, the official disclosure system of Iranian listed companies.
Codal (codal.ir, سامانه جامع اطلاع‌رسانی ناشران) is where companies and funds on the Tehran Stock Exchange, Iran Fara Bourse
and the other Iranian exchanges publish financial statements, monthly activity reports, meeting decisions and material news.
codal-mcp is an unofficial, read-only MCP server with 5 tools that turns those letters into text and tables for Claude, Cursor or Copilot.

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

For AI agents

• What: unofficial MCP server (model context protocol) for codal.ir, the disclosure system of companies and funds listed on Iranian exchanges (Tehran Stock Exchange, Iran Fara Bourse, commodity and energy exchanges, and registered unlisted companies).
• Install: uvx codal-mcp or claude mcp add codal -- uvx codal-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account. Optional CODAL_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
• Access: read-only. It cannot log in or file anything, so no confirmation is needed before calling any tool.
• Tools: 5, all prefixed cd_. Typical sequence: cd_company -> cd_search_letters -> cd_letter. cd_letter_types gives letter type ids for filtering; cd_financial_years gives a company's fiscal year ends.
• Use when: the user asks what a listed company disclosed: its latest interim or annual financial statements, EPS, monthly sales and production, shareholder meeting decisions, dividend schedule, capital increase, or the text of one Codal letter.
• Do not use when: the user wants share prices, order books or market indices (use tsetmc-mcp), or wants to trade.
• Output: compact JSON with ASCII digits. Dates are Jalali (YYYY/MM/DD), Tehran time. Report amounts are as published, usually million Rial (see unit_note).
• Rate limit: codal.ir blocks an IP for up to an hour after a burst of requests. Make few, targeted calls and reuse results. If a tool says codal.ir is rate limiting, stop and wait.
• Network: codal.ir often answers only Iranian connections. If requests time out, set CODAL_MCP_PROXY to an Iranian HTTP proxy.
• Machine-readable: server.json and the iran-mcp catalog.

Why

Everything an Iranian listed company publishes is on Codal, but behind a search form, Persian digits and report pages rendered by JavaScript, with one statement sheet per page. Answering "how did Foolad do in the first half of the year?" means finding the right letter among 1,475 and reading a table on screen. codal-mcp searches with the site's own filters and returns the statement as rows an agent can read:

You: What did Foolad (فولاد) report for its first six months of 1405?

Agent: calls cd_search_letters(symbol="فولاد", letter_type=6, period_months=6) -> cd_letter(tracing_no=1612323)

Mobarakeh Steel's unaudited six-month statements to 1405/06/31 (published 1405/07/30) show operating revenue of 2,509,422,184 million Rial, 56% more than the same period a year earlier, and a net profit of 591,629,286 million Rial, up 133%. Basic earnings per share were 308 Rial.

_{Real figures from tracing number 1612323, read with codal-mcp on 2026-10-31 and checked against the letter page on codal.ir.}

What it can do

• Search disclosures of any publisher on Codal, newest first: by symbol, letter group, letter type, words in the title, Jalali date range, report period (1-12 months) or tracing number
• List the newest letters of the whole market when no filter is given
• Read financial statements as tables, one sheet at a time: income statement, comprehensive income, balance sheet, changes in equity, cash flows and the interpretive report pages, with the unit note and listed capital
• Read monthly activity reports: raw material purchases, production and sales by product, energy use and foreign currency sources and uses
• Read text letters such as explanations, clarifications and notices, without the page's hidden form templates
• Get the links to each letter's page, PDF, Excel file and attachments (with their descriptions and dates)
• Look up companies and funds by symbol or name: ISIC code, market, kind, industry and reporting type
• List letter groups and letter types with the ids the search takes, and a company's fiscal year ends
• Read-only by design: no login, no captcha solving

Example prompts:

• "What did Foolad report in its latest interim financial statements?"
• "Show the balance sheet from that letter."
• "List Iran Khodro's monthly activity reports for 1405."
• "Which companies published monthly activity reports this week?"
• "When does Foolad's fiscal year end, and when were its last annual statements published?"
• آخرین صورت‌های مالی میان‌دوره‌ای فولاد در کدال چه بود؟
• گزارش فعالیت ماهانه مهر ۱۴۰۵ ایران خودرو را بیاور.
• تصمیمات آخرین مجمع عمومی سالیانه فولاد را از کدال بخوان.

Quick start

You need uv. No API key or account.

claude mcp add codal -- uvx codal-mcp

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

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

codex mcp add codal -- uvx codal-mcp

[mcp_servers.codal]
command = "uvx"
args = ["codal-mcp"]

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

Tools

Pass the trading symbol in Persian (فولاد, خودرو). Dates are Jalali YYYY/MM/DD; Persian digits are accepted.

All 5 tools are annotated readOnlyHint: true.

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  codal-mcp  (runs on your machine)
      │
      │  HTTPS, one request at a time, at least 2 s apart
      ├──────▶  search.codal.ir   search API, company list, letter types, fiscal years
      └──────▶  www.codal.ir      letter pages, sheets, attachment lists

codal-mcp runs locally and calls the same search API and letter pages the codal.ir website uses. It has no hosted server in between and no API key. Structured reports carry their tables as data inside the letter page; the server reads that data and returns each row as one line, in the site's column order. Other letters come back as their visible text. Requests go out through a Chrome-impersonating client, only to search.codal.ir and www.codal.ir. It only reads.

Good to know

• Rate limit. codal.ir answers HTTP 429 and shows a captcha after a burst of requests, then blocks the IP for up to an hour. The server sends one request at a time, at least 2 seconds apart, keeps the company list and letter types for 12 hours, letters for an hour and searches for 2 minutes, and never retries a 429. After a 429 it stops calling codal.ir for 10 minutes and tells the agent to wait. It never solves captchas.
• Iranian connection. codal.ir often does not answer connections from outside Iran (from a foreign VPN exit, requests timed out in our tests). Set CODAL_MCP_PROXY to an HTTP proxy with an Iranian exit. System proxy variables are ignored on purpose.
• Units. Statement and report amounts are as published, usually million Rial; unit_note quotes the page. EPS is in Rial. Divide Rial by 10 for Toman.
• Tables are text. Each table row is one line with cells separated by |. Numbers have no thousands separators, and negatives are -N where the site shows (N). Income statements have two «درصد تغيير» columns: change against the same period last year and against the last full year.
• One sheet at a time. Financial statements are split into sheets; cd_letter returns the list of sheets and takes sheet to read another one (for example 0 for the balance sheet).
• Attachments are listed, not read. Explanation letters often carry their content in an attached image or PDF. cd_letter returns the links.
• Long letters are cut at 16,000 characters (truncated); the PDF link has the whole letter.
• Search tips. period_months=12 finds annual reports, 6 half-year and 3 quarterly; title matches words in the letter title. cd_letter_types lists letter type ids (6 financial statements, 58 monthly activity report, 20 annual general meeting decisions).
• Persian text. Letter text is returned as the company wrote it, including Arabic ي/ك. Digits are converted to ASCII.
• What it does not do: no share prices (see tsetmc-mcp), no XBRL parsing, no reading of attached files, no login and no captcha solving.

FAQ

npx @modelcontextprotocol/inspector uvx codal-mcp

Configuration

فارسی: سرور MCP کدال برای دستیار هوش مصنوعی

claude mcp add codal -- uvx codal-mcp

Development

git clone https://github.com/sepehr071/codal-mcp && cd codal-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q          # offline unit tests on recorded codal.ir pages
uv run python -m pytest -m live -q  # one pass over every tool against codal.ir (about 8 requests)
uv build

All tools live in src/codal_mcp/codal.py; all HTTP, pacing and caching in src/codal_mcp/http.py. Keep the live suite small: codal.ir rate-limits hard. Issues and PRs are welcome.

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

Related servers

• tsetmc-mcp for Tehran Stock Exchange prices, order book, real vs legal trading and indices
• iran-tax-mcp for Iranian tax data: goods IDs and VAT, activity codes, property values and tax laws
• iran-mcp: catalog of all Iranian-service MCP servers

Disclaimer

Unofficial and not affiliated with or endorsed by Codal or the Securities and Exchange Organization of Iran (SEO). It is read-only and uses the search API and pages of the codal.ir website, which can change without notice. Data is informational. Nothing here is financial 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