edinet-mcp

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

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 comparison
• Parse XBRL into Polars/pandas DataFrames (BS, PL, CF)
• MCP server with 7 tools for Claude Desktop and other AI tools

Quick Start

Installation

pip install edinet-mcp
# or
uv add edinet-mcp

Get an API Key

Register (free) at EDINET and set:

export EDINET_API_KEY=your_key_here

30-Second Example

from edinet_mcp import EdinetClient

client = EdinetClient()

# Search for Toyota
companies = client.search_companies("トヨタ")
print(companies[0].name, companies[0].edinet_code)
# トヨタ自動車株式会社 E02144

# Get normalized financial statements
stmt = 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())

Financial Metrics

from edinet_mcp import EdinetClient, calculate_metrics

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

MCP Server (for Claude Desktop)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

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

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

# Start MCP server
edinet-mcp serve

API Reference

EdinetClient

client = EdinetClient(
    api_key="...",        # or EDINET_API_KEY env var
    cache_dir="~/.cache/edinet-mcp",
    rate_limit=0.5,       # requests per second
)

# Search
companies: list[Company] = client.search_companies("query")
company: Company = client.get_company("E02144")

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

# Financial statements
stmt: FinancialStatement = client.get_financial_statements(
    edinet_code="E02144",
    period="2024",
)
df = stmt.income_statement.to_polars()  # Polars DataFrame
df = stmt.income_statement.to_pandas()  # pandas DataFrame (optional dep)

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 — 57 items covering BS (23), PL (17), and CF (17). 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"}, ...]

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           # 85 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

• edinet2dataset — Sakana AI's EDINET XBRL→JSON tool
• EDINET-Bench — Financial classification benchmark
• jfinqa — Japanese financial QA benchmark (companion project)

License

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