edinet-mcp

edinet-mcp

用于日本金融数据的 EDINET XBRL 解析库和 MCP 服务。

日文版 README 请点击此处

📝 日文教程：只需向 Claude 提问，就能了解上市公司的财报（Zenn）

属于 Japan Finance Data Stack：edinet-mcp（证券申报文件） | tdnet-disclosure-mcp（及时披露） | estat-mcp（政府统计数据） | stockprice-mcp（股价和外汇）

正在构建高吞吐量管道、批量解析数千份申报文件，或者也需要 SEC EDGAR 数据？ 请查看 xbrl-facts ——一个用于 SEC + EDINET 的 Rust iXBRL 引擎，支持字节范围溯源。

效果示例

向 AI 助手提问（已连接 edinet-mcp）：

你：告诉我丰田最新的财报，以及公司列出的主要风险

Claude：根据丰田汽车（E02144）的有价证券报告书（于 2026 年 6 月 10 日提交）——

• 销售额：50.7 万亿日元（上一财年为 48.0 万亿日元，约 +5.5%）
• 业务等风险（摘自报告书正文）：汽车市场竞争加剧——随着 CASE 等技术创新不断推进，竞争将进一步加剧，也可能导致行业重组……

上述所有数字和内容都通过 get_financial_statements / get_narrative 从 EDINET 实际申报文件中获取，模型记忆中没有任何相关内容。

这是什么？

edinet-mcp 提供对日本 EDINET 金融披露系统的编程访问。它会将不同会计准则（J-GAAP / IFRS / US-GAAP）的 XBRL 申报文件规范化为统一的日文标签，并将其作为 MCP 服务提供给 AI 助手。

• 搜索 5,000 多家日本上市公司
• 获取年度、季度和半年度报告（有价证券报告书、季度报告书、半期报告书），以及临时报告书和大量持股报告书
• 自动规范化：无论采用何种会计准则，stmt["売上高"] 都能正常使用
• 双语标签：stmt["Revenue"] 同样可用（不区分大小写），MCP 工具还支持 language='en'，可输出完整英文内容
• 财务指标（ROE、ROA、利润率）及同比比较
• 将 XBRL 解析为 Polars/pandas DataFrame（BS、PL、CF）
• 多公司筛选：比较最多 20 家公司的财务指标
• 跨期差异比较（xbrl-diff）：比较不同期间的财务报表，并显示变动金额（增减额）和增长率（增减率）
• 叙述性章节：将业务等风险、MD&A、经营方针等提取为纯文本（get_narrative）
• 证据回执（可选）：针对关键数字，生成可由机器验证的声明来源记录；由 xbrl-facts Rust 引擎支持（get_receipts、pip install edinet-mcp[receipts]）
• 提供 11 个工具的 MCP 服务，可用于 Claude Desktop 和其他 AI 工具

为什么选择 edinet-mcp？

与商业 EDINET 数据 API 不同，edinet-mcp 完全免费且在本地运行：XBRL 解析器在你的机器上运行，你只需要从 FSA 获取免费的 EDINET API 密钥，而且每个数字都能追溯到原始申报文件。没有付费套餐，也没有超出 EDINET 自身速率限制的使用上限，采用 Apache-2.0 许可。

快速开始

安装

pip install edinet-mcp
# or
uv add edinet-mcp
# or with Docker
docker run -e EDINET_API_KEY=your_key ghcr.io/ajtgjmdjp/edinet-mcp serve

获取 API 密钥

在 EDINET 免费注册，然后设置：

export EDINET_API_KEY=your_key_here

30 秒示例

import asyncio
from edinet_mcp import EdinetClient

async def main():
    async with EdinetClient() as client:
        # Search for Toyota
        companies = await client.search_companies("トヨタ")
        print(companies[0].name, companies[0].edinet_code)
        # トヨタ自動車株式会社 E02144

        # Get normalized financial statements
        stmt = await client.get_financial_statements("E02144", period="2025")

        # Dict-like access — works for J-GAAP, IFRS, and US-GAAP
        revenue = stmt.income_statement["売上高"]
        print(revenue)  # {"当期": 45095325000000, "前期": 37154298000000}

        # English labels work too (case-insensitive)
        assert stmt.income_statement["Revenue"] == revenue
        print(stmt.income_statement.labels_en)
        # ["Revenue", "Cost of Sales", "Gross Profit", ...]

        # See all available line items
        print(stmt.income_statement.labels)
        # ["売上高", "売上原価", "売上総利益", "営業利益", ...]

        # Export as DataFrame
        print(stmt.income_statement.to_polars())

asyncio.run(main())

叙述性章节（定性信息）

import asyncio
from edinet_mcp import EdinetClient

async def main():
    async with EdinetClient() as client:
        # 事業等のリスク as plain text
        risks = await client.get_narrative("E02144", "business_risks")
        print(risks.text[:200])

        # Other sections: mdna, business_policy, description_of_business,
        # corporate_governance, research_and_development

asyncio.run(main())

财务指标

import asyncio
from edinet_mcp import EdinetClient, calculate_metrics

async def main():
    async with EdinetClient() as client:
        stmt = await client.get_financial_statements("E02144", period="2025")
        metrics = calculate_metrics(stmt)
        print(metrics["profitability"])
        # {"売上総利益率": "25.30%", "営業利益率": "11.87%", "ROE": "12.50%", ...}

asyncio.run(main())

多公司筛选

import asyncio
from edinet_mcp import EdinetClient, screen_companies

async def main():
    async with EdinetClient() as client:
        result = await screen_companies(
            client,
            ["E02144", "E01777", "E01967"],  # Toyota, Sony, Keyence
            period="2025",
            sort_by="営業利益率",  # Sort by operating margin
        )
        for r in result["results"]:
            print(f"{r['company_name']}: {r['profitability']['営業利益率']}")
        # 株式会社キーエンス: 51.91%
        # ソニーグループ株式会社: 11.69%
        # トヨタ自動車株式会社: 9.98%

asyncio.run(main())

跨期差异

import asyncio
from edinet_mcp import EdinetClient, diff_statements

async def main():
    async with EdinetClient() as client:
        result = await diff_statements(
            client, "E02144",
            period1="2024", period2="2025",
        )
        for d in result["diffs"][:5]:
            print(f"{d['科目']}: {d['増減額']:+,.0f} ({d['増減率']})")
        # 売上高: +7,941,027,000,000 (+21.38%)
        # 営業利益: +1,204,832,000,000 (+28.44%)
        # ...

asyncio.run(main())

MCP 服务

将以下内容添加到 AI 工具的 MCP 配置中：

{
  "mcpServers": {
    "edinet": {
      "command": "uvx",
      "args": ["edinet-mcp", "serve"],
      "env": {
        "EDINET_API_KEY": "your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "edinet": {
      "command": "uvx",
      "args": ["edinet-mcp", "serve"],
      "env": {
        "EDINET_API_KEY": "your_key_here"
      }
    }
  }
}

claude mcp add edinet -- uvx edinet-mcp serve
# Then set EDINET_API_KEY in your environment

然后向 AI 提问：“请告诉我丰田最新的营业利润。”

可用的 MCP 工具

注意：period 参数指的是文件提交年份，而非财年。财年在 3 月结束的日本公司会在次年 6 月提交年度报告（例如：FY2024 → 2025 年提交 → period="2025"）。

CLI

# Search companies
edinet-mcp search トヨタ

# Fetch income statement
edinet-mcp statements -c E02144 -p 2024

# Screen multiple companies
edinet-mcp screen E02144 E01777 E02529 --sort-by ROE

# Compare across periods (xbrl-diff)
edinet-mcp diff -c E02144 -p1 2023 -p2 2024

# Start MCP server
edinet-mcp serve

API 参考

EdinetClient

所有客户端方法均为异步方法。请使用 async with 正确清理资源：

import asyncio
from edinet_mcp import EdinetClient

async def main():
    async with EdinetClient(
        api_key="...",        # or EDINET_API_KEY env var
        cache_dir="~/.cache/edinet-mcp",
        rate_limit=0.5,       # requests per second
    ) as client:
        # Search
        companies: list[Company] = await client.search_companies("query")
        company: Company = await client.get_company("E02144")

        # Filings
        filings: list[Filing] = await client.get_filings(
            start_date="2024-01-01",
            edinet_code="E02144",
            doc_type="annual_report",
        )

        # Financial statements (by edinet_code + period)
        stmt: FinancialStatement = await client.get_financial_statements(
            edinet_code="E02144",
            period="2024",  # Filing year (not fiscal year)
        )

        # Or get the most recent filing (within past 365 days)
        stmt = await client.get_financial_statements(edinet_code="E02144")

        df = stmt.income_statement.to_polars()  # Polars DataFrame
        df = stmt.income_statement.to_pandas()  # pandas DataFrame (optional dep)

asyncio.run(main())

Filing

get_filings() 返回的 Filing 对象具有以下属性：

for filing in filings:
    print(filing.description)    # "有価証券報告書－第121期(...)"
    print(filing.filing_date)    # datetime.date(2025, 6, 18)
    print(filing.doc_id)         # "S100VWVY"
    print(filing.company_name)   # "トヨタ自動車株式会社"
    print(filing.period_start)   # datetime.date(2024, 4, 1)
    print(filing.period_end)     # datetime.date(2025, 3, 31)

StatementData

每份财务报表（BS、PL、CF）都是可像字典一样访问的 StatementData 对象：

# Dict-like access by Japanese label
stmt.income_statement["売上高"]       # → {"当期": 45095325, "前期": 37154298}
stmt.income_statement.get("営業利益") # → {"当期": 5352934} or None
stmt.income_statement.labels          # → ["売上高", "営業利益", ...]

# DataFrame export
stmt.balance_sheet.to_polars()    # → polars.DataFrame
stmt.balance_sheet.to_pandas()    # → pandas.DataFrame (requires pandas)
stmt.balance_sheet.to_dicts()     # → list[dict]
len(stmt.balance_sheet)           # number of line items

# Raw XBRL data preserved
stmt.income_statement.raw_items   # original pre-normalization data

标准化

edinet-mcp 会自动跨会计准则标准化 XBRL 元素名称：

映射定义在 taxonomy.yaml 中，共 161 个项目，涵盖 PL（42）、BS（79）和 CF（40）；IFRS/US-GAAP 元素的变体会通过后缀剥离自动解析。编辑 YAML 文件即可添加新映射，无需修改代码。

from edinet_mcp import get_taxonomy_labels

# Discover available labels
labels = get_taxonomy_labels("income_statement")
# [{"id": "revenue", "label": "売上高", "label_en": "Revenue"}, ...]

EDINET 后缀剥离

EDINET 会在 XBRL 元素名称后附加会计准则和特定章节的后缀（例如，TotalAssetsIFRSSummaryOfBusinessResults）。系统会自动剥离这些后缀，以匹配规范化的分类条目。非合并（单体）上下文会被过滤，以优先采用合并数据。

架构

EDINET API → Parser (XBRL/TSV) → Normalizer (taxonomy.yaml) → MCP Server
                                        ↓
                              StatementData["売上高"]
                              calculate_metrics(stmt)
                              compare_periods(stmt)

开发

git clone https://github.com/ajtgjmdjp/edinet-mcp
cd edinet-mcp
uv sync --extra dev
uv run pytest -v           # 336 tests
uv run ruff check src/

数据归属

本项目使用 EDINET 提供的数据。EDINET（面向投资者的电子披露网络）由日本金融厅（金融庁）运营。 EDINET 数据依据公共数据许可 1.0提供。

相关项目

日本金融数据技术栈（由同一作者开发）：

• tdnet-disclosure-mcp — TDNET 及时披露（适时开示）
• estat-mcp — 政府统计数据（e-Stat）
• stockprice-mcp — 股价与外汇汇率（yfinance）
• jfinqa — 日本金融问答基准

社区项目：

• edinet2dataset — Sakana AI 的 EDINET XBRL→JSON 工具
• EDINET-Bench — 财务分类基准

许可证

Apache-2.0。第三方归属信息请参阅 NOTICE。