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 — 金融分類基準