codal-mcp
Unofficial read-only MCP server for Codal (codal.ir), the disclosure system of Iranian listed companies: search filings, read financial statements, EPS and monthly activity reports as tables, meeting decisions, PDF and Excel links. Tehran Stock Exchange and Fara Bourse.
Install / Use
claude mcp add sepehr071 -- npx -y github:sepehr071/codal-mcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Finance & AccountingSupported Platforms
Our assessment of codal-mcp
codal-mcp scores 84/100 on our quality scale, 67th of 102 Finance & Accounting skills we index.
Its MCP Server is 19 KB long, well organised into 16 sections with 10 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 5 days ago, so codal-mcp is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
codal-mcp compared with similar skills
All 4 of these similar skills score higher than codal-mcp; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| codal-mcp (this skill)by sepehr071 | 84 | 10 | 5d ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| CowAgentby zhayujie | 100 | 48.0k | today | CLAUDE.md |
Frequently asked questions
- How do I install codal-mcp?
- Run
claude mcp add sepehr071 -- npx -y github:sepehr071/codal-mcp. The install tabs above show the steps for each supported agent. - Which AI agents does codal-mcp work with?
- It is written for Claude Code, Claude Desktop, Cursor and GitHub Copilot, as a MCP Server file. Other agents that read the same format can often use it too.
- Is codal-mcp safe to use?
- It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is codal-mcp still maintained?
- The repository was last updated 5 days ago, so codal-mcp is actively maintained.
Skill content
View source on GitHubcodal-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.<br> Codal (codal.ir, سامانه جامع اطلاعرسانی ناشران) is where companies and funds on the Tehran Stock Exchange, Iran Fara Bourse<br> and the other Iranian exchanges publish financial statements, monthly activity reports, meeting decisions and material news.<br> 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 · فارسی
</div>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.
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.
<sub>Real figures from tracing number 1612323, read with codal-mcp on 2026-10-31 and checked against the letter page on codal.ir.</sub>
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?"
- <span dir="rtl">آخرین صورتهای مالی میاندورهای فولاد در کدال چه بود؟</span>
- <span dir="rtl">گزارش فعالیت ماهانه مهر ۱۴۰۵ ایران خودرو را بیاور.</span>
- <span dir="rtl">تصمیمات آخرین مجمع عمومی سالیانه فولاد را از کدال بخوان.</span>
Quick start
You need uv. No API key or account.
<details open> <summary><b>Claude Code</b></summary>claude mcp add codal -- uvx codal-mcp
</details>
<details>
<summary><b>Claude Desktop</b></summary>
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"codal": { "command": "uvx", "args": ["codal-mcp"] }
}
}
</details>
<details>
<summary><b>Cursor</b></summary>
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"] }
}
}
</details>
<details>
<summary><b>Codex CLI</b></summary>
codex mcp add codal -- uvx codal-mcp
Or in ~/.codex/config.toml:
[mcp_servers.codal]
command = "uvx"
args = ["codal-mcp"]
</details>
<details>
<summary><b>Gemini CLI</b></summary>
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"codal": { "command": "uvx", "args": ["codal-mcp"] }
}
}
</details>
<details>
<summary><b>Windsurf</b></summary>
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.
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 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)
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
CowAgent
48.0kOpen-source personal AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
