edinet-mcp

EDINET XBRL parsing library and MCP server for Japanese financial data.

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

Part of the Japan Finance Data Stack: edinet-mcp (securities filings) | tdnet-disclosure-mcp (timely disclosures) | estat-mcp (government statistics) | boj-mcp (Bank of Japan) | stockprice-mcp (stock prices & FX)

What is this?

edinet-mcp provides programmatic access to Japan's EDINET financial disclosure system. It normalizes XBRL filings across accounting standards (J-GAAP / IFRS / US-GAAP) into canonical Japanese labels and exposes them as an MCP server for AI assistants.

• Search 5,000+ listed Japanese companies
• Retrieve annual/quarterly financial reports (有価証券報告書, 四半期報告書)
• Automatic normalization: stmt["売上高"] works regardless of accounting standard
• Financial metrics (ROE, ROA, profit margins) and year-over-year comparisons
• Parse XBRL into Polars/pandas DataFrames (BS, PL, CF)
• Multi-company screening: Compare financial metrics across up to 20 companies
• Cross-period diff (xbrl-diff): Compare financial statements across periods with change amounts (増減額) and growth rates (増減率)
• MCP server with 9 tools for Claude Desktop and other AI tools

Quick Start

Installation

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

Get an API Key

Register (free) at EDINET and set:

export EDINET_API_KEY=your_key_here

30-Second Example

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}

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

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

asyncio.run(main())

Financial Metrics

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())

Multi-Company Screening

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())

Cross-Period Diff

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 Server

Add to your AI tool's MCP config:

{
  "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

Then ask your AI: "トヨタの最新の営業利益を教えて"

Available MCP Tools

Note: The period parameter is the filing year, not the fiscal year. Japanese companies with a March fiscal year-end file annual reports in June of the following year (e.g., FY2024 → filed 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 Reference

EdinetClient

All client methods are async. Use async with for proper resource cleanup:

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
        max_retries=3,        # retry on 429/5xx with exponential backoff
    ) 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

Filing objects returned by get_filings() have the following attributes:

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

Each financial statement (BS, PL, CF) is a StatementData object with dict-like access:

# 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

Normalization

edinet-mcp automatically normalizes XBRL element names across accounting standards:

Mappings are defined in taxonomy.yaml — 161 items covering PL (42), BS (79), and CF (40), with IFRS/US-GAAP element variants automatically resolved via suffix stripping. Add new mappings by editing the YAML file, no code changes needed.

from edinet_mcp import get_taxonomy_labels

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

EDINET Suffix Stripping

EDINET appends accounting-standard and section-specific suffixes to XBRL element names (e.g., TotalAssetsIFRSSummaryOfBusinessResults). These are automatically stripped to match canonical taxonomy entries. Non-consolidated (単体) contexts are filtered out to prefer consolidated figures.

Architecture

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

Development

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

Data Attribution

This project uses data from EDINET (Electronic Disclosure for Investors' NETwork), operated by the Financial Services Agency of Japan (金融庁). EDINET data is provided under the Public Data License 1.0.

Related Projects

Japan Finance Data Stack (by same author):

• tdnet-disclosure-mcp — TDNET timely disclosures (適時開示)
• estat-mcp — Government statistics (e-Stat)
• boj-mcp — Bank of Japan statistics
• stockprice-mcp — Stock prices & FX rates (yfinance)
• jfinqa — Japanese financial QA benchmark

Community:

• edinet2dataset — Sakana AI's EDINET XBRL→JSON tool
• EDINET-Bench — Financial classification benchmark

License

Apache-2.0. See NOTICE for third-party attributions.