# edinet-mcp
EDINET XBRL parsing library and MCP server for Japanese financial data.
[](https://pypi.org/project/edinet-mcp/)
[](https://pypi.org/project/edinet-mcp/)
[](LICENSE)
## What is this?
**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.
- 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
```bash
pip install edinet-mcp
# or
uv add edinet-mcp
```
### Get an API Key
Register (free) at [EDINET](https://disclosure2dl.edinet-fsa.go.jp/guide/static/disclosure/WZEK0110.html) and set:
```bash
export EDINET_API_KEY=your_key_here
```
### 30-Second Example
```python
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
```python
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`):
```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
```bash
# Search companies
edinet-mcp search トヨタ
# Fetch income statement
edinet-mcp statements -c E02144 -p 2024
# Start MCP server
edinet-mcp serve
```
## API Reference
### `EdinetClient`
```python
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:
```python
# 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:
| Accounting Standard | XBRL Element | Normalized Label |
|---|---|---|
| J-GAAP | `NetSales` | 売上高 |
| IFRS | `Revenue` | 売上高 |
| US-GAAP | `Revenues` | 売上高 |
Mappings are defined in [`taxonomy.yaml`](src/edinet_mcp/data/taxonomy.yaml) — 57 items covering BS (23), PL (17), and CF (17). Add new mappings by editing the YAML file, no code changes needed.
```python
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
```bash
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](https://disclosure.edinet-fsa.go.jp/)
(Electronic Disclosure for Investors' NETwork), operated by the
Financial Services Agency of Japan (金融庁).
EDINET data is provided under the [Public Data License 1.0](https://www.digital.go.jp/resources/open_data/).
## Related Projects
- [edinet2dataset](https://github.com/SakanaAI/edinet2dataset) — Sakana AI's EDINET XBRL→JSON tool
- [EDINET-Bench](https://github.com/SakanaAI/EDINET-Bench) — Financial classification benchmark
- [jfinqa](https://github.com/ajtgjmdjp/jfinqa) — Japanese financial QA benchmark (companion project)
## License
Apache-2.0. See [NOTICE](NOTICE) for third-party attributions.
