Codal (کدال) Disclosures

codal-mcp：面向 AI Agent 的 Codal（کدال）披露信息和财务报表 MCP 服务

codal-mcp 可让 AI Agent 搜索和读取 Codal，即伊朗上市公司的官方披露系统。
Codal（codal.ir，سامانه جامع اطلاع‌رسانی ناشران）是德黑兰证券交易所、伊朗法拉证券交易所
以及伊朗其他交易所的公司和基金发布财务报表、月度活动报告、会议决议和重大新闻的地方。
codal-mcp 是一个非官方、只读的 MCP 服务，包含 5 个工具，可将这些公告转换为文本和表格，供 Claude、Cursor 或 Copilot 使用。

面向 AI Agent · 快速开始 · 功能 · 工具 · 常见问题 · فارسی

面向 AI Agent

• 简介： 面向 codal.ir 的非官方 MCP 服务（模型上下文协议），用于查询在伊朗交易所（德黑兰证券交易所、伊朗法拉证券交易所、商品和能源交易所以及注册的非上市公司）上市的公司和基金披露信息。
• 安装： uvx codal-mcp 或 claude mcp add codal -- uvx codal-mcp。传输方式：stdio。需要 uv（Python 3.10+）。
• 身份验证： 无需身份验证、API 密钥或账户。可选设置 CODAL_MCP_PROXY（HTTP 代理 URL 或逗号分隔的列表）；系统代理设置将被忽略。
• 访问权限： 只读。它无法登录或提交任何内容，因此调用任何工具前都不需要确认。
• 工具： 共 5 个，名称均以 cd_ 为前缀。典型调用顺序：cd_company -> cd_search_letters -> cd_letter。 cd_letter_types 可提供用于筛选的信函类型 ID；cd_financial_years 可提供公司的财年结束日期。
• 适用场景： 用户询问上市公司披露了什么内容，例如最新的中期或年度财务报表、EPS、月度销售和产量、股东大会决议、股息安排、增资，或某封 Codal 信函的文本。
• 不适用场景： 用户想查询股价、订单簿或市场指数（请使用 tsetmc-mcp），或想进行交易。
• 输出： 紧凑的 JSON，使用 ASCII 数字。日期采用波斯历（YYYY/MM/DD），时区为德黑兰时间。报告金额按发布时的单位显示，通常为百万里亚尔（参见 unit_note）。
• 速率限制： codal.ir 在短时间内收到大量请求后，会封锁 IP，最长可达一小时。请少量、针对性地调用，并重复利用结果。如果工具提示 codal.ir 正在限流，请停止请求并等待。
• 网络： codal.ir 通常只响应来自伊朗的连接。如果请求超时，请将 CODAL_MCP_PROXY 设置为伊朗 HTTP 代理。
• 机器可读信息： server.json 和 iran-mcp 目录。

为什么

伊朗上市公司发布的所有信息都在 Codal 上，但需要通过搜索表单查找，数字使用波斯数字，报告页面由 JavaScript 渲染，而且每页只有一张报表。要回答“Foolad 上半年业绩如何？”，就得从 1,475 封公告中找到合适的一封，再阅读屏幕上的表格。codal-mcp 使用该网站自带的筛选条件进行搜索，并以 Agent 可读取的行形式返回报表：

你： Foolad（فولاد）在 1405 年前六个月的报告中披露了什么？

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

Mobarakeh Steel 截至 1405/06/31 的未经审计六个月报表（发布于 1405/07/30）显示，营业收入为 2,509,422,184 百万里亚尔，比上年同期增长 56%；净利润为 591,629,286 百万里亚尔，增长 133%。基本每股收益为 308 里亚尔。

_{这些真实数据来自跟踪编号 1612323，由 codal-mcp 于 2026-10-31 读取，并与 codal.ir 上的公告页面核对。}

功能

• 搜索披露信息：按股票代码、公告分组、公告类型、标题中的词语、贾拉利日期范围、报告期间（1-12 个月）或跟踪编号搜索 Codal 上任何发布方的信息，结果按最新优先排列
• 列出最新公告：未提供筛选条件时，列出全市场最新公告
• 读取财务报表：以表格形式逐页读取，包括利润表、综合收益表、资产负债表、权益变动表、现金流量表和解释性报告页面，并提供计量单位说明和上市资本
• 读取月度活动报告：包括原材料采购、按产品划分的产量和销量、能源使用情况以及外汇来源与用途
• 读取文字公告：例如说明、澄清和通知，不包含页面中隐藏的表单模板
• 获取公告链接：获取每封公告的页面、PDF、Excel 文件和附件链接（含其说明和日期）
• 查询公司和基金：按股票代码或名称查找 ISIC 代码、市场、类型、行业和报告类型
• 列出公告分组和公告类型：提供搜索所需的 ID，以及公司的财年结束日期
• 按设计仅支持读取：无需登录，也不解决验证码

示例提示词：

• “Foolad 最新的中期财务报表披露了什么？”
• “显示该公告中的资产负债表。”
• “列出 Iran Khodro 在 1405 年的月度活动报告。”
• “本周有哪些公司发布了月度活动报告？”
• “Foolad 的财年何时结束？最近一次年度报表是什么时候发布的？”
• آخرین صورت‌های مالی میان‌دوره‌ای فولاد در کدال چه بود؟
• گزارش فعالیت ماهانه مهر ۱۴۰۵ ایران خودرو را بیاور.
• تصمیمات آخرین مجمع عمومی سالیانه فولاد را از کدال بخوان.

快速开始

你需要安装 uv。无需 API 密钥或账户。

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"] }
  }
}

请使用波斯语传入交易代码（فولاد、خودرو）。日期采用波斯历 YYYY/MM/DD 格式；也接受波斯数字。

这 5 个工具均标注为 readOnlyHint: true。

工作原理

  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 在本地运行，并调用 codal.ir 网站使用的同一搜索 API 和函件页面。中间没有托管服务，也不需要 API 密钥。结构化报告会将表格作为数据嵌入函件页面；服务端读取这些数据，并按网站的列顺序将每行作为一行返回。其他函件则以其可见文本返回。请求通过模拟 Chrome 的客户端发出，且只发送到 search.codal.ir 和 www.codal.ir。它只读取数据。

注意事项

• 速率限制。 codal.ir 遇到短时间内大量请求时会返回 HTTP 429 并显示验证码，随后封禁该 IP，最长可达一小时。服务端每次只发送一个请求，间隔至少 2 秒；公司列表和函件类型缓存 12 小时，函件缓存一小时，搜索结果缓存 2 分钟，并且绝不重试 429。收到 429 后，服务端会在 10 分钟内停止调用 codal.ir，并提示 Agent 等待。它绝不会尝试破解验证码。
• 伊朗网络连接。 codal.ir 经常无法响应来自伊朗境外的连接（在我们的测试中，使用外国 VPN 出口时，请求会超时）。请将 CODAL_MCP_PROXY 设置为使用伊朗出口的 HTTP 代理。系统代理变量会被有意忽略。
• 单位。 报表和报告中的金额按发布时的单位显示，通常为百万里亚尔；unit_note 会引用页面中的说明。每股收益（EPS）的单位是里亚尔。里亚尔除以 10 即为土曼。
• 表格为文本。 每行表格占一行，单元格以 | 分隔。数字不带千位分隔符；网站以 (N) 显示的负数会写作 -N。利润表有两列「درصد تغيير」：分别表示与去年同期和上一完整财年的变化。
• 一次读取一个工作表。 财务报表分为多个工作表；cd_letter 会返回 sheets 列表，并接受 sheet 参数以读取其他工作表（例如，资产负债表对应 0）。
• 列出附件，但不读取。 说明函件通常会将内容放在附件图片或 PDF 中。cd_letter 会返回这些附件的链接。
• 较长的函件会截断至 16,000 个字符（truncated）；PDF 链接则包含完整函件。
• 搜索提示。 period_months=12 可查找年度报告，6 可查找半年度报告，3 可查找季度报告；title 可匹配函件标题中的词语。cd_letter_types 会列出函件类型 ID（6 为财务报表，58 为月度活动报告，20 为年度股东大会决议）。
• 波斯语文本。 函件文本会按公司原文返回，包括阿拉伯字母 ي/ك。数字会转换为 ASCII 格式。
• **不支持的功能：**不提供股价（请参阅 tsetmc-mcp）、不解析 XBRL、不读取附件文件、不登录，也不破解验证码。

常见问题

npx @modelcontextprotocol/inspector uvx codal-mcp

配置

فارسی：面向 AI 助手的 Codal MCP 服务

claude mcp add codal -- uvx codal-mcp

开发

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

所有工具都位于 src/codal_mcp/codal.py；所有 HTTP、请求间隔控制和缓存都位于 src/codal_mcp/http.py。请保持在线测试套件精简：codal.ir 的速率限制很严格。欢迎提交问题和 PR。

发布版本：更新 pyproject.toml 和 server.json 中的版本，然后推送一个 v* 标签。GitHub Actions 会发布到 PyPI。

相关服务

• tsetmc-mcp：提供德黑兰证券交易所的价格、订单簿、真实与法人交易以及指数信息
• iran-tax-mcp：提供伊朗税务数据，包括商品 ID 和增值税、经营活动代码、房产价值及税法
• iran-mcp：伊朗各类服务 MCP 服务的目录

免责声明

本项目为非官方项目，与 Codal 或伊朗证券交易组织（SEO）无关联，也未得到其认可。 本项目为只读服务，使用 codal.ir 网站的搜索 API 和网页；这些内容可能在不另行通知的情况下发生变化。数据仅供参考。本文内容不构成任何财务建议。

作者

由 Sepehr Radmard（سپهر رادمرد）构建并维护。欢迎通过 LinkedIn 联系，或在 GitHub 关注 @sepehr071，获取更多面向伊朗网站的 MCP 服务。所有服务均列在 iran-mcp 中。如果本项目为您节省了时间，请给仓库点个星，帮助更多人发现它。

许可证

MIT