Edinet MCP

🚀 edinet-mcp

edinet-mcp 是一个用于解析日本金融数据的 EDINET XBRL 库，同时还提供 MCP 服务器。它可以帮助用户以编程方式访问日本的 EDINET 财务披露系统，将不同会计准则下的 XBRL 文件标准化为规范的日语标签，并通过 MCP 服务器为 AI 助手提供数据。

📝 日本語チュートリアル: Claude に聞くだけで上場企業の決算がわかる (Zenn)

它是 Japan Finance Data Stack 的一部分：edinet-mcp（证券备案文件） | tdnet-disclosure-mcp（及时披露信息） | estat-mcp（政府统计数据） | boj-mcp（日本银行数据） | stockprice-mcp（股票价格和外汇汇率）

🚀 快速开始

安装

pip install edinet-mcp
# 或者
uv add edinet-mcp
# 或者使用 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:
        # 搜索丰田
        companies = await client.search_companies("トヨタ")
        print(companies[0].name, companies[0].edinet_code)
        # トヨタ自動車株式会社 E02144

        # 获取标准化的财务报表
        stmt = await client.get_financial_statements("E02144", period="2025")

        # 像字典一样访问数据 —— 适用于 J-GAAP、IFRS 和 US-GAAP
        revenue = stmt.income_statement["売上高"]
        print(revenue)  # {"当期": 45095325000000, "前期": 37154298000000}

        # 查看所有可用的行项目
        print(stmt.income_statement.labels)
        # ["売上高", "売上原価", "売上総利益", "営業利益", ...]

        # 导出为 DataFrame
        print(stmt.income_statement.to_polars())

asyncio.run(main())

✨ 主要特性

• 搜索 5000 多家日本上市公司。
• 获取年度/季度财务报告（有価証券報告書、四半期報告書）。
• 自动标准化：无论使用何种会计准则，stmt["売上高"] 都能正常工作。
• 计算财务指标（ROE、ROA、利润率）并进行同比比较。
• 将 XBRL 文件解析为 Polars/pandas DataFrame（资产负债表、利润表、现金流量表）。
• 多公司筛选：最多比较 20 家公司的财务指标。
• 跨期差异比较（xbrl-diff）：比较不同期间的财务报表，显示变化金额（増減額）和增长率（増減率）。
• 为 Claude Desktop 和其他 AI 工具提供包含 9 个工具的 MCP 服务器。

📦 安装指南

pip install edinet-mcp
# 或者
uv add edinet-mcp
# 或者使用 Docker
docker run -e EDINET_API_KEY=your_key ghcr.io/ajtgjmdjp/edinet-mcp serve

💻 使用示例

基础用法

import asyncio
from edinet_mcp import EdinetClient

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

        # 获取标准化的财务报表
        stmt = await client.get_financial_statements("E02144", period="2025")

        # 像字典一样访问数据 —— 适用于 J-GAAP、IFRS 和 US-GAAP
        revenue = stmt.income_statement["売上高"]
        print(revenue)  # {"当期": 45095325000000, "前期": 37154298000000}

        # 查看所有可用的行项目
        print(stmt.income_statement.labels)
        # ["売上高", "売上原価", "売上総利益", "営業利益", ...]

        # 导出为 DataFrame
        print(stmt.income_statement.to_polars())

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"],  # 丰田、索尼、基恩士
            period="2025",
            sort_by="営業利益率",  # 按营业利润率排序
        )
        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
# 然后在你的环境中设置 EDINET_API_KEY

然后向你的 AI 提问："トヨタの最新の営業利益を教えて"

可用的 MCP 工具

⚠️ 重要提示

period 参数是 备案年份，而不是会计年度。会计年度于 3 月结束的日本公司会在次年 6 月提交年度报告（例如，2024 财年 → 2025 年提交 → period="2025"）。

CLI

# 搜索公司
edinet-mcp search トヨタ

# 获取利润表
edinet-mcp statements -c E02144 -p 2024

# 筛选多家公司
edinet-mcp screen E02144 E01777 E02529 --sort-by ROE

# 跨期比较（xbrl-diff）
edinet-mcp diff -c E02144 -p1 2023 -p2 2024

# 启动 MCP 服务器
edinet-mcp serve

API 参考

EdinetClient

所有客户端方法都是异步的。使用 async with 进行资源的正确清理：

import asyncio
from edinet_mcp import EdinetClient

async def main():
    async with EdinetClient(
        api_key="...",        # 或者使用 EDINET_API_KEY 环境变量
        cache_dir="~/.cache/edinet-mcp",
        rate_limit=0.5,       # 每秒请求数
        max_retries=3,        # 遇到 429/5xx 错误时进行指数退避重试
    ) as client:
        # 搜索
        companies: list[Company] = await client.search_companies("query")
        company: Company = await client.get_company("E02144")

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

        # 财务报表（按 edinet_code 和期间）
        stmt: FinancialStatement = await client.get_financial_statements(
            edinet_code="E02144",
            period="2024",  # 备案年份（不是会计年度）
        )

        # 或者获取最近的备案文件（过去 365 天内）
        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（可选依赖）

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

每个财务报表（资产负债表、利润表、现金流量表）都是一个 StatementData 对象，可以像字典一样访问：

# 按日语标签像字典一样访问
stmt.income_statement["売上高"]       # → {"当期": 45095325, "前期": 37154298}
stmt.income_statement.get("営業利益") # → {"当期": 5352934} 或 None
stmt.income_statement.labels          # → ["売上高", "営業利益", ...]

# 导出为 DataFrame
stmt.balance_sheet.to_polars()    # → polars.DataFrame
stmt.balance_sheet.to_pandas()    # → pandas.DataFrame（需要 pandas）
stmt.balance_sheet.to_dicts()     # → list[dict]
len(stmt.balance_sheet)           # 行项目数量

# 保留原始 XBRL 数据
stmt.income_statement.raw_items   # 原始的标准化前数据

标准化

edinet-mcp 会自动对不同会计准则下的 XBRL 元素名称进行标准化：

映射关系定义在 中 —— 涵盖利润表（42 项）、资产负债表（79 项）和现金流量表（40 项）的 161 个项目，IFRS/US-GAAP 元素变体通过后缀剥离自动解析。通过编辑 YAML 文件添加新的映射，无需更改代码。

from edinet_mcp import get_taxonomy_labels

# 查找可用的标签
labels = get_taxonomy_labels("income_statement")
# [{"id": "revenue", "label": "売上高", "label_en": "Revenue"}, ...]

EDINET 后缀剥离

EDINET 会在 XBRL 元素名称后附加特定于会计准则和部分的后缀（例如，TotalAssetsIFRSSummaryOfBusinessResults）。这些后缀会被自动剥离，以匹配规范的分类条目。非合并（単体）上下文会被过滤掉，优先选择合并数据。

🔧 技术细节

EDINET API → 解析器 (XBRL/TSV) → 标准化器 (taxonomy.yaml) → MCP 服务器
                                        ↓
                              StatementData["売上高"]
                              calculate_metrics(stmt)
                              compare_periods(stmt)

📄 许可证

本项目采用 Apache-2.0 许可证。有关第三方归属信息，请参阅 NOTICE。

数据归属

本项目使用了由日本金融厅（金融庁）运营的 EDINET（Electronic Disclosure for Investors' NETwork）的数据。EDINET 数据根据 Public Data License 1.0 提供。

相关项目

Japan Finance Data Stack（同一作者）：

• tdnet-disclosure-mcp — TDNET 及时披露信息
• estat-mcp — 政府统计数据
• boj-mcp — 日本银行统计数据
• stockprice-mcp — 股票价格和外汇汇率（yfinance）
• jfinqa — 日本金融问答基准

社区项目：

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