codal-mcp
Unofficial read-only MCP server for searching and reading Codal disclosures and financial statements of Iranian listed companies.
Search Codal letters/disclosures by symbol, category, letter type, title words, Jalali date range, report period, or tracing number, newest first and 20 per page.
Read one Codal letter as text or financial statement tables, one sheet at a time, with links to its page, PDF, Excel, and attachments.
Find companies and funds by Persian symbol or name, including market, industry, and type.
List Codal letter groups and letter type IDs for filtering searches.
List a company's fiscal year-end dates in Jalali.
Read financial statements, monthly activity reports, meeting decisions, dividend schedules, capital increase notices, and explanatory letters.
It is read-only and does not provide share prices, trading, XBRL parsing, attached-file reading, login, or investment advice.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@codal-mcp What did Foolad report for its first six months of 1405?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcporclaude 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_typesgives letter type ids for filtering;cd_financial_yearsgives 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 (seeunit_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_PROXYto an Iranian HTTP proxy.Machine-readable:
server.jsonand 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-mcpSettings → 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-mcpOr 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 |
| Search codal.ir disclosures (letters) of Iranian listed companies, newest first, 20 per page |
| Read one codal.ir letter: its text or tables, plus links to its page, PDF, Excel and attachments |
| Find companies and funds on codal.ir by symbol or name, with their market, industry and type |
| List codal.ir letter groups, or the letter types of one group with the ids |
| 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_PROXYto 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_notequotes 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-Nwhere 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_letterreturns the list ofsheetsand takessheetto read another one (for example0for the balance sheet).Attachments are listed, not read. Explanation letters often carry their content in an attached image or PDF.
cd_letterreturns the links.Long letters are cut at 16,000 characters (
truncated); the PDF link has the whole letter.Search tips.
period_months=12finds annual reports,6half-year and3quarterly;titlematches words in the letter title.cd_letter_typeslists 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-mcpConfiguration
Variable | Default | Meaning |
| 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 buildAll 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)
استفادهٔ شخصی و غیرتجاری رایگان است. استفاده در شرکت، محصول پولی یا پروژهٔ مشتری به مجوز تجاری نیاز دارد؛ از راه لینکدین یا گیت‌هاب با سپهر رادمرد تماس بگیرید. متن کامل: 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 toolscd_companyFind a company on CodalARead-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 companyARead-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 letterARead-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 typesARead-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 disclosuresARead-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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Korean company facts in English for AI agents: ~830 KOSPI-listed companies (DART profiles, KRW financials, recent filings) and ~110,000 corporate public procurement suppliers (12-month KONEPS contract awards), plus live National Tax Service business status checks. 4 tools, keyless, read-only.
SEC-filed company financials with filing citations, plus market data, for AI agents
SEC EDGAR financials, insider trading, and economic data for AI agents. US GAAP + IFRS.
Primary-source SEC filing intelligence and financial/disclosure reconciliation for AI agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables 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.8210 PyPI10PolyForm Noncommercial 1.0.0
- AlicenseAqualityBmaintenanceEnables 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.1199 PyPIPolyForm Noncommercial 1.0.0
- AlicenseAqualityBmaintenanceEnables 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.16100 PyPIPolyForm Noncommercial 1.0.0
- AlicenseAqualityBmaintenanceEnables 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.22122 PyPI2PolyForm Noncommercial 1.0.0