{
  "markdown": "# edinet-mcp\n\nEDINET XBRL parsing library and MCP server for Japanese financial data.\n\n[日本語版READMEはこちら](README_ja.md)\n\n[![PyPI](https://img.shields.io/pypi/v/edinet-mcp)](https://pypi.org/project/edinet-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/edinet-mcp)](https://pypi.org/project/edinet-mcp/)\n[![CI](https://github.com/ajtgjmdjp/edinet-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ajtgjmdjp/edinet-mcp/actions/workflows/ci.yml)\n[![Downloads](https://img.shields.io/pypi/dm/edinet-mcp)](https://pypi.org/project/edinet-mcp/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)\n[![ClawHub](https://img.shields.io/badge/ClawHub-edinet--mcp-orange)](https://clawhub.com/skills/edinet-mcp)\n\n📝 [日本語チュートリアル: Claude に聞くだけで上場企業の決算がわかる (Zenn)](https://zenn.dev/ajtgjmdjp/articles/edinet-mcp-claude-desktop)\n\nPart of the [Japan Finance Data Stack](https://github.com/ajtgjmdjp/awesome-japan-finance-data): **edinet-mcp** (securities filings) | [tdnet-disclosure-mcp](https://github.com/ajtgjmdjp/tdnet-disclosure-mcp) (timely disclosures) | [estat-mcp](https://github.com/ajtgjmdjp/estat-mcp) (government statistics) | [stockprice-mcp](https://github.com/ajtgjmdjp/stockprice-mcp) (stock prices & FX)\n\n> Building a high-throughput pipeline, batch-parsing thousands of filings, or\n> need SEC EDGAR coverage too? See [xbrl-facts](https://github.com/ajtgjmdjp/xbrl-facts)\n> — a Rust iXBRL engine for SEC + EDINET with byte-range provenance.\n\n## What it looks like\n\n<!-- TODO: replace with a short GIF of a real Claude Desktop session -->\n\nAsk your AI assistant (with edinet-mcp connected):\n\n> **You**: トヨタの最新の決算と、会社が挙げている主要なリスクを教えて\n>\n> **Claude**: トヨタ自動車 (E02144) の有価証券報告書（2026年6月10日提出）によると——\n> - **売上高**: 50.7兆円（前期 48.0兆円、約 +5.5%）\n> - **事業等のリスク**（有報本文より）: 自動車市場の競争激化 — CASE などの技術革新が進むことで競争は一層激化し、業界再編につながる可能性も指摘 …\n\nEvery number and passage above is fetched from the actual EDINET filing via\n`get_financial_statements` / `get_narrative` — nothing comes from the model's memory.\n\n## What is this?\n\n**edinet-mcp** provides programmatic access to Japan's [EDINET](https://disclosure.edinet-fsa.go.jp/) 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](https://modelcontextprotocol.io/) server for AI assistants.\n\n- Search 5,000+ listed Japanese companies\n- Retrieve annual/quarterly/semiannual reports (有価証券報告書, 四半期報告書, 半期報告書) plus extraordinary (臨時報告書) and large shareholding (大量保有報告書) filings\n- **Automatic normalization**: `stmt[\"売上高\"]` works regardless of accounting standard\n- **Bilingual labels**: `stmt[\"Revenue\"]` works too (case-insensitive), and the MCP tool supports `language='en'` for fully English output\n- Financial metrics (ROE, ROA, profit margins) and year-over-year comparisons\n- Parse XBRL into Polars/pandas DataFrames (BS, PL, CF)\n- **Multi-company screening**: Compare financial metrics across up to 20 companies\n- **Cross-period diff (xbrl-diff)**: Compare financial statements across periods with change amounts (増減額) and growth rates (増減率)\n- **Narrative sections**: extract 事業等のリスク, MD&A, 経営方針 and more as plain text (`get_narrative`)\n- **Evidence receipts** (optional): machine-verifiable claim-to-source records for key figures, backed by the [xbrl-facts](https://github.com/ajtgjmdjp/xbrl-facts) Rust engine (`get_receipts`, `pip install edinet-mcp[receipts]`)\n- MCP server with 11 tools for Claude Desktop and other AI tools\n\n### Why edinet-mcp?\n\nUnlike commercial EDINET data APIs, edinet-mcp is **fully free and local**: the\nXBRL parser runs on your machine, the only credential you need is a free EDINET\nAPI key from the FSA, and every number is traceable to the original filing.\nNo paid tiers, no usage caps beyond EDINET's own rate limits, Apache-2.0 licensed.\n\n## Quick Start\n\n### Installation\n\n```bash\npip install edinet-mcp\n# or\nuv add edinet-mcp\n# or with Docker\ndocker run -e EDINET_API_KEY=your_key ghcr.io/ajtgjmdjp/edinet-mcp serve\n```\n\n### Get an API Key\n\nRegister (free) at [EDINET](https://disclosure2dl.edinet-fsa.go.jp/guide/static/disclosure/WZEK0110.html) and set:\n\n```bash\nexport EDINET_API_KEY=your_key_here\n```\n\n### 30-Second Example\n\n```python\nimport asyncio\nfrom edinet_mcp import EdinetClient\n\nasync def main():\n    async with EdinetClient() as client:\n        # Search for Toyota\n        companies = await client.search_companies(\"トヨタ\")\n        print(companies[0].name, companies[0].edinet_code)\n        # トヨタ自動車株式会社 E02144\n\n        # Get normalized financial statements\n        stmt = await client.get_financial_statements(\"E02144\", period=\"2025\")\n\n        # Dict-like access — works for J-GAAP, IFRS, and US-GAAP\n        revenue = stmt.income_statement[\"売上高\"]\n        print(revenue)  # {\"当期\": 45095325000000, \"前期\": 37154298000000}\n\n        # English labels work too (case-insensitive)\n        assert stmt.income_statement[\"Revenue\"] == revenue\n        print(stmt.income_statement.labels_en)\n        # [\"Revenue\", \"Cost of Sales\", \"Gross Profit\", ...]\n\n        # See all available line items\n        print(stmt.income_statement.labels)\n        # [\"売上高\", \"売上原価\", \"売上総利益\", \"営業利益\", ...]\n\n        # Export as DataFrame\n        print(stmt.income_statement.to_polars())\n\nasyncio.run(main())\n```\n\n### Narrative Sections (定性情報)\n\n```python\nimport asyncio\nfrom edinet_mcp import EdinetClient\n\nasync def main():\n    async with EdinetClient() as client:\n        # 事業等のリスク as plain text\n        risks = await client.get_narrative(\"E02144\", \"business_risks\")\n        print(risks.text[:200])\n\n        # Other sections: mdna, business_policy, description_of_business,\n        # corporate_governance, research_and_development\n\nasyncio.run(main())\n```\n\n### Financial Metrics\n\n```python\nimport asyncio\nfrom edinet_mcp import EdinetClient, calculate_metrics\n\nasync def main():\n    async with EdinetClient() as client:\n        stmt = await client.get_financial_statements(\"E02144\", period=\"2025\")\n        metrics = calculate_metrics(stmt)\n        print(metrics[\"profitability\"])\n        # {\"売上総利益率\": \"25.30%\", \"営業利益率\": \"11.87%\", \"ROE\": \"12.50%\", ...}\n\nasyncio.run(main())\n```\n\n### Multi-Company Screening\n\n```python\nimport asyncio\nfrom edinet_mcp import EdinetClient, screen_companies\n\nasync def main():\n    async with EdinetClient() as client:\n        result = await screen_companies(\n            client,\n            [\"E02144\", \"E01777\", \"E01967\"],  # Toyota, Sony, Keyence\n            period=\"2025\",\n            sort_by=\"営業利益率\",  # Sort by operating margin\n        )\n        for r in result[\"results\"]:\n            print(f\"{r['company_name']}: {r['profitability']['営業利益率']}\")\n        # 株式会社キーエンス: 51.91%\n        # ソニーグループ株式会社: 11.69%\n        # トヨタ自動車株式会社: 9.98%\n\nasyncio.run(main())\n```\n\n### Cross-Period Diff\n\n```python\nimport asyncio\nfrom edinet_mcp import EdinetClient, diff_statements\n\nasync def main():\n    async with EdinetClient() as client:\n        result = await diff_statements(\n            client, \"E02144\",\n            period1=\"2024\", period2=\"2025\",\n        )\n        for d in result[\"diffs\"][:5]:\n            print(f\"{d['科目']}: {d['増減額']:+,.0f} ({d['増減率']})\")\n        # 売上高: +7,941,027,000,000 (+21.38%)\n        # 営業利益: +1,204,832,000,000 (+28.44%)\n        # ...\n\nasyncio.run(main())\n```\n\n## MCP Server\n\nAdd to your AI tool's MCP config:\n\n<details>\n<summary><b>Claude Desktop</b> (~⁠/Library/Application Support/Claude/claude_desktop_config.json)</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"edinet\": {\n      \"command\": \"uvx\",\n      \"args\": [\"edinet-mcp\", \"serve\"],\n      \"env\": {\n        \"EDINET_API_KEY\": \"your_key_here\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>Cursor</b> (~⁠/.cursor/mcp.json)</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"edinet\": {\n      \"command\": \"uvx\",\n      \"args\": [\"edinet-mcp\", \"serve\"],\n      \"env\": {\n        \"EDINET_API_KEY\": \"your_key_here\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>Claude Code</b></summary>\n\n```bash\nclaude mcp add edinet -- uvx edinet-mcp serve\n# Then set EDINET_API_KEY in your environment\n```\n</details>\n\nThen ask your AI: \"トヨタの最新の営業利益を教えて\"\n\n### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `search_companies` | 企業名・証券コード・EDINETコードで検索 |\n| `get_filings` | 指定期間の開示書類一覧を取得 |\n| `get_financial_statements` | 正規化された財務諸表 (BS/PL/CF) を取得 |\n| `get_financial_metrics` | ROE・ROA・利益率等の財務指標を計算 |\n| `compare_financial_periods` | 前年比較（増減額・増減率） |\n| `screen_companies` | 複数企業の財務指標を一括比較（最大20社） |\n| `get_narrative` | 定性情報（事業等のリスク・MD&A 等）をページング付きで取得 |\n| `get_receipts` | 主要科目の検証可能な evidence receipt を取得（要 `[receipts]` extra） |\n| `list_available_labels` | 取得可能な財務科目の一覧 |\n| `get_company_info` | 企業の詳細情報を取得 |\n| `diff_financial_statements` | 2期間の財務諸表を比較（増減額・増減率） |\n\n> **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\"`).\n\n## CLI\n\n```bash\n# Search companies\nedinet-mcp search トヨタ\n\n# Fetch income statement\nedinet-mcp statements -c E02144 -p 2024\n\n# Screen multiple companies\nedinet-mcp screen E02144 E01777 E02529 --sort-by ROE\n\n# Compare across periods (xbrl-diff)\nedinet-mcp diff -c E02144 -p1 2023 -p2 2024\n\n# Start MCP server\nedinet-mcp serve\n```\n\n## API Reference\n\n### `EdinetClient`\n\nAll client methods are async. Use `async with` for proper resource cleanup:\n\n```python\nimport asyncio\nfrom edinet_mcp import EdinetClient\n\nasync def main():\n    async with EdinetClient(\n        api_key=\"...\",        # or EDINET_API_KEY env var\n        cache_dir=\"~/.cache/edinet-mcp\",\n        rate_limit=0.5,       # requests per second\n    ) as client:\n        # Search\n        companies: list[Company] = await client.search_companies(\"query\")\n        company: Company = await client.get_company(\"E02144\")\n\n        # Filings\n        filings: list[Filing] = await client.get_filings(\n            start_date=\"2024-01-01\",\n            edinet_code=\"E02144\",\n            doc_type=\"annual_report\",\n        )\n\n        # Financial statements (by edinet_code + period)\n        stmt: FinancialStatement = await client.get_financial_statements(\n            edinet_code=\"E02144\",\n            period=\"2024\",  # Filing year (not fiscal year)\n        )\n\n        # Or get the most recent filing (within past 365 days)\n        stmt = await client.get_financial_statements(edinet_code=\"E02144\")\n\n        df = stmt.income_statement.to_polars()  # Polars DataFrame\n        df = stmt.income_statement.to_pandas()  # pandas DataFrame (optional dep)\n\nasyncio.run(main())\n```\n\n### `Filing`\n\nFiling objects returned by `get_filings()` have the following attributes:\n\n```python\nfor filing in filings:\n    print(filing.description)    # \"有価証券報告書－第121期(...)\"\n    print(filing.filing_date)    # datetime.date(2025, 6, 18)\n    print(filing.doc_id)         # \"S100VWVY\"\n    print(filing.company_name)   # \"トヨタ自動車株式会社\"\n    print(filing.period_start)   # datetime.date(2024, 4, 1)\n    print(filing.period_end)     # datetime.date(2025, 3, 31)\n```\n\n### `StatementData`\n\nEach financial statement (BS, PL, CF) is a `StatementData` object with dict-like access:\n\n```python\n# Dict-like access by Japanese label\nstmt.income_statement[\"売上高\"]       # → {\"当期\": 45095325, \"前期\": 37154298}\nstmt.income_statement.get(\"営業利益\") # → {\"当期\": 5352934} or None\nstmt.income_statement.labels          # → [\"売上高\", \"営業利益\", ...]\n\n# DataFrame export\nstmt.balance_sheet.to_polars()    # → polars.DataFrame\nstmt.balance_sheet.to_pandas()    # → pandas.DataFrame (requires pandas)\nstmt.balance_sheet.to_dicts()     # → list[dict]\nlen(stmt.balance_sheet)           # number of line items\n\n# Raw XBRL data preserved\nstmt.income_statement.raw_items   # original pre-normalization data\n```\n\n### Normalization\n\nedinet-mcp automatically normalizes XBRL element names across accounting standards:\n\n| Accounting Standard | XBRL Element | Normalized Label |\n|---|---|---|\n| J-GAAP | `NetSales` | 売上高 |\n| IFRS | `Revenue`, `SalesRevenuesIFRS` | 売上高 |\n| US-GAAP | `Revenues` | 売上高 |\n\nMappings are defined in [`taxonomy.yaml`](src/edinet_mcp/data/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.\n\n```python\nfrom edinet_mcp import get_taxonomy_labels\n\n# Discover available labels\nlabels = get_taxonomy_labels(\"income_statement\")\n# [{\"id\": \"revenue\", \"label\": \"売上高\", \"label_en\": \"Revenue\"}, ...]\n```\n\n### EDINET Suffix Stripping\n\nEDINET 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.\n\n## Architecture\n\n```\nEDINET API → Parser (XBRL/TSV) → Normalizer (taxonomy.yaml) → MCP Server\n                                        ↓\n                              StatementData[\"売上高\"]\n                              calculate_metrics(stmt)\n                              compare_periods(stmt)\n```\n\n## Development\n\n```bash\ngit clone https://github.com/ajtgjmdjp/edinet-mcp\ncd edinet-mcp\nuv sync --extra dev\nuv run pytest -v           # 336 tests\nuv run ruff check src/\n```\n\n## Data Attribution\n\nThis project uses data from [EDINET](https://disclosure.edinet-fsa.go.jp/)\n(Electronic Disclosure for Investors' NETwork), operated by the\nFinancial Services Agency of Japan (金融庁).\nEDINET data is provided under the [Public Data License 1.0](https://www.digital.go.jp/resources/open_data/).\n\n## Related Projects\n\n**Japan Finance Data Stack** (by same author):\n- [tdnet-disclosure-mcp](https://github.com/ajtgjmdjp/tdnet-disclosure-mcp) — TDNET timely disclosures (適時開示)\n- [estat-mcp](https://github.com/ajtgjmdjp/estat-mcp) — Government statistics (e-Stat)\n- [stockprice-mcp](https://github.com/ajtgjmdjp/stockprice-mcp) — Stock prices & FX rates (yfinance)\n- [jfinqa](https://github.com/ajtgjmdjp/jfinqa) — Japanese financial QA benchmark\n\n**Community**:\n- [edinet2dataset](https://github.com/SakanaAI/edinet2dataset) — Sakana AI's EDINET XBRL→JSON tool\n- [EDINET-Bench](https://github.com/SakanaAI/EDINET-Bench) — Financial classification benchmark\n\n## License\n\nApache-2.0. See [NOTICE](NOTICE) for third-party attributions.\n\n<!-- mcp-name: io.github.ajtgjmdjp/edinet-mcp -->\n",
  "bytes": 14436,
  "sha": "b20cb2aaaca38368bbcace2d5822021bacc39ddb04bf00f8072f2315718ba6c2",
  "repo_slug": "ajtgjmdjp/edinet-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ajtgjmdjp_edinet_mcp_f48b2270/readme"
}