Skip to main content
Glama
codal-mcp

codal-mcp

by sepehr071

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.

PyPI Python CI MCP Registry License: PolyForm Noncommercial

Install in VS Code

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.

Related MCP server: fipiran-mcp

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

Settings → Developer → Edit Config, then add:

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

Add the Claude Desktop block above to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

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

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

Or in ~/.codex/config.toml:

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

Add to ~/.gemini/settings.json:

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

Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.

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

Tools

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

Tool

What it does

cd_search_letters

Search codal.ir disclosures (letters) of Iranian listed companies, newest first, 20 per page

cd_letter

Read one codal.ir letter: its text or tables, plus links to its page, PDF, Excel and attachments

cd_company

Find companies and funds on codal.ir by symbol or name, with their market, industry and type

cd_letter_types

List codal.ir letter groups, or the letter types of one group with the ids cd_search_letters takes

cd_financial_years

List the fiscal year-end dates codal.ir knows for one company, newest first (Jalali)

All 5 tools are annotated readOnlyHint: true.

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 60 seconds 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

Codal (codal.ir, سامانه جامع اطلاع‌رسانی ناشران) is the official disclosure system run under Iran's Securities and Exchange Organization (SEO). Companies and funds listed on the Tehran Stock Exchange, Iran Fara Bourse and the other Iranian exchanges publish their financial statements, monthly activity reports, meeting notices and decisions, capital increases and material news there. About 5,400 publishers are on it.

Add codal-mcp to your agent, then ask in plain language. The agent finds the letter with cd_search_letters (for example symbol="فولاد", letter_type=6, period_months=6) and reads it with cd_letter(tracing_no=...), which returns the income statement as rows; sheet=0 gives the balance sheet.

There is no documented public API. codal-mcp uses the same search API and letter pages that the codal.ir website uses, without login, and returns compact JSON.

Often not directly: codal.ir did not answer requests from a foreign VPN exit in our tests. Run it on an Iranian connection, or set CODAL_MCP_PROXY to an HTTP proxy with an Iranian exit.

codal.ir blocks an IP for up to an hour after many requests in a short time. The server spaces and caches requests to avoid it; if it still happens, wait and ask again with fewer calls. Results you already have stay valid.

tsetmc-mcp gives market data from the Tehran Stock Exchange: prices, order book, trades and indices. codal-mcp gives what the companies themselves publish: statements, reports and notices. Use both for a full picture of a stock.

No. It returns the tables as the site shows them; the agent can compute ratios from the rows. For a spreadsheet, use the excel link that cd_letter returns.

No. It only reads what companies published. Nothing it returns is financial advice.

npx @modelcontextprotocol/inspector uvx codal-mcp

Configuration

Variable

Default

Meaning

CODAL_MCP_PROXY

unset

Optional HTTP proxy URL for codal.ir requests; system proxy settings are ignored. A comma-separated list is used one at a time: the next proxy takes over when one is blocked or cannot connect

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

پروژه codal-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای کدال (codal.ir) است، سامانه‌ای که شرکت‌ها و صندوق‌های بورس تهران، فرابورس و بقیه بورس‌های ایران اطلاعیه‌ها و صورت‌های مالی خود را در آن منتشر می‌کنند. با این سرور، دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اطلاعیه‌های کدال را جستجو می‌کند و متن و جدول‌های آن‌ها را می‌خواند.

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

  • جستجوی اطلاعیه‌ها با نماد، گروه و نوع اطلاعیه، کلمه‌های عنوان، بازه تاریخ شمسی، طول دوره گزارش یا شماره پیگیری؛ جدیدترین‌ها اول.

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

  • خواندن گزارش فعالیت ماهانه: خرید مواد اولیه، تولید و فروش هر محصول، مصرف انرژی و منابع و مصارف ارزی.

  • متن اطلاعیه‌های توضیحی و شفاف‌سازی، همراه با لینک PDF، فایل اکسل و پیوست‌ها.

  • جستجوی شرکت‌ها و صندوق‌ها با نماد یا نام، با کد آیسیک، بازار، صنعت و سال‌های مالی.

نکته‌ها

  • فقط اطلاعات منتشرشده را می‌خواند؛ وارد حسابی نمی‌شود و توصیه سرمایه‌گذاری نیست.

  • مبلغ‌ها همان‌طور است که در کدال آمده، معمولاً میلیون ریال. تاریخ‌ها شمسی است.

  • کدال بعد از تعداد زیادی درخواست، دسترسی را تا یک ساعت می‌بندد. این سرور درخواست‌ها را یکی‌یکی و با فاصله دست‌کم ۲ ثانیه می‌فرستد و نتیجه را نگه می‌دارد.

  • کدال معمولاً فقط به اینترنت ایران جواب می‌دهد. اگر درخواست‌ها بی‌جواب ماند، متغیر CODAL_MCP_PROXY را روی یک پراکسی HTTP با خروجی ایران بگذارید.

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

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

claude mcp add codal -- uvx codal-mcp

در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.

نمونه پرسش‌ها

  • «آخرین صورت‌های مالی شش‌ماهه فولاد را بیاور و سود خالص را با پارسال مقایسه کن.»

  • «ترازنامه همان اطلاعیه را هم نشان بده.»

  • «گزارش‌های فعالیت ماهانه ایران خودرو در سال ۱۴۰۵ را فهرست کن.»

  • «این هفته کدام شرکت‌ها گزارش فعالیت ماهانه منتشر کرده‌اند؟»

  • «سال مالی فولاد کی تمام می‌شود؟»

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.

  • 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)

استفادهٔ شخصی و غیرتجاری رایگان است. استفاده در شرکت، محصول پولی یا پروژهٔ مشتری به مجوز تجاری نیاز دارد؛ از راه لینکدین یا گیت‌هاب با سپهر رادمرد تماس بگیرید. متن کامل: PolyForm Noncommercial 1.0.0. نسخه‌های پیش از 0.2.2 با مجوز MIT منتشر شده‌اند و همان مجوز را دارند.

Free for personal and non-commercial use under the PolyForm Noncommercial License 1.0.0. Using it in a company, a paid product or a client project needs a commercial license: contact Sepehr Radmard on LinkedIn or GitHub. Versions before 0.2.2 were released under MIT and stay under it.

Available Tools

5 tools
cd_companyFind a company on CodalA
Read-onlyIdempotent

Find companies and funds on codal.ir by symbol or name, with their market, industry and type.

Use it to get the exact symbol for cd_search_letters and cd_financial_years. Exact matches first, then prefix, then name contains; listed before unlisted. matched is the total number of hits.

Inputs: query (required), limit.

cd_financial_yearsFiscal years of a companyA
Read-onlyIdempotent

List the fiscal year-end dates codal.ir knows for one company, newest first (Jalali).

Use it before searching annual statements with cd_search_letters (period_months 12). An empty list usually means a wrong symbol: check cd_company.

Inputs: symbol (required).

cd_letterRead one Codal letterA
Read-onlyIdempotent

Read one codal.ir letter: its text or tables, plus links to its page, PDF, Excel and attachments.

Structured reports come back as tables (one line per row, cells joined by ' | ', usually million Rial; see unit_note), one sheet at a time: sheets lists them, call again with sheet for another. Other letters give text. attachments are the company's files. Cut at 16,000 characters (truncated); the PDF has all.

Inputs: tracing_no (required), sheet.

cd_letter_typesList Codal letter typesA
Read-onlyIdempotent

List codal.ir letter groups, or the letter types of one group with the ids cd_search_letters takes.

No argument: the 11 groups. With category: its types; use a type id as letter_type in cd_search_letters.

Inputs: category.

cd_search_lettersSearch Codal disclosuresA
Read-onlyIdempotent

Search codal.ir disclosures (letters) of Iranian listed companies, newest first, 20 per page.

No filters lists the newest letters of all companies. total = matches, pages = page count. Pass a letter's tracing_no to cd_letter to read it. No results: check the symbol with cd_company or widen filters.

Inputs: page, title, symbol, to_date, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool maps to a distinct step of the workflow: resolve company (cd_company), browse taxonomy (cd_letter_types), find disclosures (cd_search_letters), then read one (cd_letter), with cd_financial_years as a narrow helper. The only mild overlap is between cd_letter_types and cd_search_letters (both deal with letter types), but the descriptions explicitly explain the id hand-off between them.

    Naming Consistency4/5

    All names share a consistent `cd_` prefix and snake_case form, making the family obvious at a glance. The pattern is mostly noun-phrase based (cd_letter, cd_company, cd_financial_years) with one verb-first outlier (cd_search_letters), a minor deviation that remains readable.

    Tool Count5/5

    Five tools is tightly scoped and every one earns its place: search, read, and three reference resolvers that the search/read tools explicitly depend on. Nothing feels redundant or padded for a read-only disclosure-reading server.

    Completeness4/5

    The surface covers the full read path — discovery via search, taxonomy lookup, entity resolution, fiscal-period resolution, and full letter retrieval with tables, attachments, and export links. Minor gaps exist (no way to page through or fetch multiple letters in one call, no direct attachment/PDF download tool), but agents can work around these via the returned links.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to read Tehran Stock Exchange and Iran Fara Bourse market data—quotes, top movers, order books, price history, sector indices, and real vs legal trading—through read-only tools. Requires no API key, returning compact JSON in Rial directly to Claude, Cursor, or Copilot.
      8
      210 PyPI
      10
      PolyForm Noncommercial 1.0.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search, rank, and compare Iranian mutual funds and ETFs; inspect NAV, returns, size, flows, investors, and managers; and retrieve Tehran and Farabourse market overviews, indices, stock quotes, and industry data read-only without an API key.
      11
      99 PyPI
      PolyForm Noncommercial 1.0.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to query public Iran Fara Bourse data read-only, including bond, sukuk and treasury bill yields, instrument and coupon details, live quotes and order books, IPOs, announcements, news and market statistics.
      16
      100 PyPI
      PolyForm Noncommercial 1.0.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to read Tehran Stock Exchange data through Mofid and Agah brokers, including stocks, ETFs and funds, options, bonds and sukuk, gold and coin prices, screeners, and Codal announcements without an API key or broker account.
      22
      122 PyPI
      2
      PolyForm Noncommercial 1.0.0