Edinet MCP

🚀 edinet-mcp

edinet-mcp is a library for parsing EDINET XBRL and an MCP server for Japanese financial data. It offers programmatic access to Japan's EDINET financial disclosure system, normalizes XBRL filings across different accounting standards, and exposes them as an MCP server for AI assistants.

📝 Japanese Tutorial: Understand Listed Companies' Financial Results Just by Asking 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)

✨ Features

• Search over 5,000 listed Japanese companies.
• Retrieve annual and quarterly financial reports (Securities Report, Quarterly Report).
• Automatic normalization: stmt["Revenue"] works regardless of the accounting standard.
• Calculate financial metrics (ROE, ROA, profit margins) and perform year-over-year comparisons.
• Parse XBRL into Polars/pandas DataFrames (Balance Sheet, Income Statement, Cash Flow Statement).
• 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 (for free) at EDINET and set:

export EDINET_API_KEY=your_key_here

💻 Usage Examples

Basic Usage

import asyncio
from edinet_mcp import EdinetClient

async def main():
    async with EdinetClient() as client:
        # Search for Toyota
        companies = await client.search_companies("Toyota")
        print(companies[0].name, companies[0].edinet_code)
        # Toyota Motor Corporation 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["Revenue"]
        print(revenue)  # {"Current period": 45095325000000, "Previous period": 37154298000000}

        # See all available line items
        print(stmt.income_statement.labels)
        # ["Revenue", "Cost of sales", "Gross profit", "Operating profit", ...]

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

asyncio.run(main())

Advanced Usage - 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"])
        # {"Gross profit margin": "25.30%", "Operating profit margin": "11.87%", "ROE": "12.50%", ...}

asyncio.run(main())

Advanced Usage - 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="Operating profit margin",  # Sort by operating margin
        )
        for r in result["results"]:
            print(f"{r['company_name']}: {r['profitability']['Operating profit margin']}")
        # Keyence Corporation: 51.91%
        # Sony Group Corporation: 11.69%
        # Toyota Motor Corporation: 9.98%

asyncio.run(main())

Advanced Usage - 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['Account']}: {d['Change amount']:+,.0f} ({d['Change rate']})")
        # Revenue: +7,941,027,000,000 (+21.38%)
        # Operating profit: +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: "Tell me Toyota's latest operating profit."

Available MCP Tools

⚠️ Important 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 Toyota

# 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

📚 Documentation

EdinetClient

All client methods are asynchronous. 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)    # "Securities Report - 121st period (...)"
    print(filing.filing_date)    # datetime.date(2025, 6, 18)
    print(filing.doc_id)         # "S100VWVY"
    print(filing.company_name)   # "Toyota Motor Corporation"
    print(filing.period_start)   # datetime.date(2024, 4, 1)
    print(filing.period_end)     # datetime.date(2025, 3, 31)

StatementData

Each financial statement (Balance Sheet, Income Statement, Cash Flow Statement) is a StatementData object with dict-like access:

# Dict-like access by Japanese label
stmt.income_statement["Revenue"]       # → {"Current period": 45095325, "Previous period": 37154298}
stmt.income_statement.get("Operating profit") # → {"Current period": 5352934} or None
stmt.income_statement.labels          # → ["Revenue", "Operating profit", ...]

# 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 — 161 items covering Income Statement (42), Balance Sheet (79), and Cash Flow Statement (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": "Revenue", "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.

🔧 Technical Details

EDINET API → Parser (XBRL/TSV) → Normalizer (taxonomy.yaml) → MCP Server
                                        ↓
                              StatementData["Revenue"]
                              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 the 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

This project is licensed under the Apache-2.0 license. See NOTICE for third-party attributions.