edinet-mcp 0.3.0

EDINET XBRL parsing library and MCP server for Japanese financial data

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

Tool	Description
search_companies	企業名・証券コード・EDINETコードで検索
get_filings	指定期間の開示書類一覧を取得
get_financial_statements	正規化された財務諸表 (BS/PL/CF) を取得
get_financial_metrics	ROE・ROA・利益率等の財務指標を計算
compare_financial_periods	前年比較（増減額・増減率）
list_available_labels	取得可能な財務科目の一覧
get_company_info	企業の詳細情報を取得

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

# 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",
)

# Access Filing 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)

# Financial statements (by edinet_code + period)
stmt: FinancialStatement = 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 = 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)

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

Filing

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

filing.doc_id          # str: Document ID (e.g., "S100VWVY")
filing.edinet_code     # str: Company EDINET code (e.g., "E02144")
filing.company_name    # str: Company name
filing.description     # str: Document description (e.g., "有価証券報告書－第121期(...)")
filing.filing_date     # datetime.date: Submission date
filing.period_start    # datetime.date | None: Reporting period start
filing.period_end      # datetime.date | None: Reporting period end
filing.doc_type        # DocType: Document type enum
filing.has_xbrl        # bool: XBRL data available
filing.has_pdf         # bool: PDF available
filing.has_csv         # bool: CSV available

Normalization

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

Accounting Standard	XBRL Element	Normalized Label
J-GAAP	NetSales	売上高
IFRS	Revenue, SalesRevenuesIFRS	売上高
US-GAAP	Revenues	売上高

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           # 179 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.