# edinet-mcp

[![CI](https://github.com/reanimatedead/edinet-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/reanimatedead/edinet-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/edinet-mcp.svg)](https://www.npmjs.com/package/edinet-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.reanimatedead%2Fedinet--mcp-blue)](https://registry.modelcontextprotocol.io/servers/io.github.reanimatedead/edinet-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

> [!WARNING]
> **保守停止・非推奨 / Maintenance discontinued — deprecated (2026-07-29).**
> This project is no longer maintained. The market has moved to a point where equivalent functionality — normalized EDINET financial data for Japanese listed companies — is available **for free** from existing services, so there is no longer a sustainable reason to maintain an independent offering built on the same freely available public data. The repository stays public as a reference implementation, but no further updates, fixes, or data refreshes will be published.
>
> **Recommended alternative: [edinetdb.jp](https://edinetdb.jp)** — please use it for current, maintained EDINET data.

**Ask your MCP client (Claude Desktop, etc.) about Japanese company financials in plain English — income statement, balance sheet and cash-flow items for ~3,600 listed Japanese (non-financial) companies, normalized to English keys and JPY, sourced from Japan's FSA EDINET annual securities reports.** For analysts, investors and developers who want EDINET numbers without an API key, XBRL parsing, or Japanese tag names.

> Data attribution: EDINET (Financial Services Agency, Japan). Not investment advice.

## How this differs from other EDINET / Japan-finance MCP servers

Typical EDINET integrations wrap the official EDINET v2 API directly. That means
each user must issue an API key, and each request pulls filing archives whose
XBRL still has to be parsed and mapped. This server takes a different trade-off:

- **Zero setup.** No API key, no signup, no rate limit. Read-only against a
  pre-built public JSON dataset (`https://edinet-api-base.pages.dev/api/`) —
  no re-fetching from EDINET at query time, no local database.
- **Pre-normalized, comparable output.** English keys, absolute JPY, accounting
  standard auto-detected (**IFRS / Japanese GAAP / US GAAP**), consolidation and
  source document included. Items that don't exist under a company's standard
  come back as `null` **with a reason** — never approximated.
- **Defensive by default.** Every upstream response is schema-validated at
  runtime (Ajv). If the dataset ever changes shape, tools return a structured
  `upstream_invalid` error instead of crashing or passing through garbage, and
  responses carry a `freshness_warning` when the underlying data is older than
  a threshold (`EDINET_STALE_DAYS`, default 30 days).
- **Comparison built in.** `compare_companies` returns side-by-side values plus
  derived operating/net margins, so a single tool call answers the common
  "A vs B" question.

## Quick start

Run from source (60 seconds, no npm publish required):

```bash
git clone https://github.com/reanimatedead/edinet-mcp.git && cd edinet-mcp
npm install && npm run build
```

Add to `claude_desktop_config.json`
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "edinet": { "command": "node", "args": ["/absolute/path/to/edinet-mcp/dist/server.js"] }
  }
}
```

Restart Claude Desktop. Then try:

> **"Compare Toyota and Nintendo's operating margins."**

Claude will call `search_company` → `compare_companies` and answer with real figures, e.g.
Toyota (7203) operating margin ≈ 7.4%, Nintendo (7974) ≈ 15.6% (FY ending 2026-03, values in JPY).

Once the package is published to npm, the zero-clone alternative is:

```json
{
  "mcpServers": {
    "edinet": { "command": "npx", "args": ["-y", "edinet-mcp"] }
  }
}
```

## Honest limitations

- **Annual reports only.** Figures come from annual securities reports (有価証券報告書),
  latest fiscal year per company. No quarterly data, no historical time series.
- **Non-financial companies only (~3,600).** Banks, insurers and securities firms are
  excluded because their statement structure differs.
- **Freshness depends on the upstream dataset.** This server does not re-fetch from
  EDINET; it serves what the static dataset contains. Responses include a
  `freshness_warning` once data age exceeds the threshold, but staleness itself
  can't be fixed on this side.
- **Single upstream host.** The public JSON lives on one CDN-backed host. Runtime
  validation makes failures explicit and structured, but there is no fallback mirror.
- **Cross-standard comparability has limits.** Normalization is faithful to each
  company's accounting standard; items that don't exist under a standard are `null`
  with a reason. Comparing IFRS vs J-GAAP lines is on you.
- **Not investment advice.** Values are as filed; derived ratios are presentation-only
  arithmetic on served values.

## Tools

| Tool | What it does |
|---|---|
| `search_company` | Find companies by name (EN/JA) or 4-digit code. Resolve a name → code. |
| `get_financials` | Up to 17 income-statement / balance-sheet / cash-flow items + metadata for one company. |
| `compare_companies` | Compare 2+ companies on selected metrics; also returns derived `operating_margin_pct` / `net_margin_pct`. |
| `list_companies` | Browse/filter the universe by `industry` and/or `accounting_standard`. |

## Tool usage examples

`search_company` — resolve a name/code to companies:
```json
{ "name": "search_company", "arguments": { "query": "Toyota", "limit": 3 } }
// → { results: [ { sec_code: "7203", name_en: "TOYOTA MOTOR CORPORATION", accounting_standard: "IFRS", ... } ] }
```

`get_financials` — 17 items + metadata for one company:
```json
{ "name": "get_financials", "arguments": { "code": "7974" } }
// → { company:{sec_code:"7974", name_en:"Nintendo Co., Ltd."},
//     fiscal_year:{accounting_standard:"Japanese GAAP", ...},
//     flat_values:{ revenue: 2313051000000, operating_income: 360117000000, ... },
//     unavailable:[ { key:"equity_attributable_to_owners", reason:"..." } ] }
```

`compare_companies` — side-by-side + derived margins:
```json
{ "name": "compare_companies", "arguments": { "codes": ["7203", "7974"] } }
// → companies: [
//     { code:"7203", values:{revenue:50684952000000, operating_income:3766216000000, ...},
//       derived_ratios:{ operating_margin_pct: 7.43, net_margin_pct: ... } },
//     { code:"7974", ..., derived_ratios:{ operating_margin_pct: 15.57 } } ]
```

`list_companies` — browse/filter the universe:
```json
{ "name": "list_companies", "arguments": { "accounting_standard": "US GAAP", "limit": 10 } }
// → { total_matched: 5, results: [ { sec_code:"6301", name_en:"KOMATSU LTD." }, ... ] }
```

All monetary values are in JPY (absolute yen). `derived_ratios` are computed from the served values (presentation only — no re-extraction).

## Configuration
- `EDINET_API_BASE_URL` (optional): override the data source base (default `https://edinet-api-base.pages.dev/api`).
- `EDINET_STALE_DAYS` (optional): data-age threshold in days for `freshness_warning` (default `30`).

## Development
```bash
npm run dev        # run from source (tsx)
npm test           # unit tests (mocked fetch, offline)
npm run typecheck
npm run build      # → dist/
node scripts/mcp-smoke.mjs   # end-to-end MCP client smoke against live data
```

CI (GitHub Actions) runs typecheck, tests and build on every push/PR. Publishing to
npm is a separate, manual-only workflow (`workflow_dispatch`) — nothing publishes
automatically.

## Publishing to npm — HUMAN_ACTION_REQUIRED
`npm publish` needs an authenticated npm account (browser/OTP) — it cannot be automated here.
The package is publish-ready (`build` output in `dist`, `bin`, `files`, English README). Steps:
```bash
cd edinet-mcp
npm login                 # HUMAN: browser/OTP auth
npm run build             # ensure dist/ is fresh
npm publish --access public
```
After publishing, Option A (`npx -y edinet-mcp`) works for everyone.

## Where to find it
- **MCP Registry**: `io.github.reanimatedead/edinet-mcp` (manifest: [`server.json`](./server.json), validate with `npm run validate:server`).
- **awesome-mcp-servers**: listed under Finance & Fintech.
- Auto-indexed by Glama / PulseMCP (public repo, `mcp` topic). Submission status & steps: [`docs/mcp-listing.md`](./docs/mcp-listing.md).

## License
MIT. Underlying data © their sources; usage follows the [EDINET terms of use](https://disclosure2.edinet-fsa.go.jp/).