Skip to main content
Glama
Indonesia Financial Data MCP

Indonesia Financial Data MCP

README.md
# Indonesia Financial Data MCP

Citation-first MCP server for **official Indonesian financial data**. The official
tools below do not use Yahoo Finance or yfinance. Optional market-data tools
(labelled `market_*` / `ownership_holders`) are provided separately through the
MIT-licensed [fzn0x/idx](https://github.com/fzn0x/idx) CLI and are always
labelled `official: false` — see "Market data (optional, non-official)".

## Official sources

| Provider | Coverage | Access |
|---|---|---|
| IDX | Issuer directory, detailed company profile, management/shareholders, announcements, financial-report attachments (XLSX/PDF/XBRL) | Public web endpoints; session cookie initialized automatically |
| BPS | Subjects, variables, dynamic statistical tables | Official WebAPI; requires free `BPS_API_KEY` |
| KSEI | SID growth and investor demographics | Public JSON endpoints |

Every successful response has:

```json
{
  "data": {},
  "provenance": [
    {
      "provider": "IDX",
      "source_url": "https://www.idx.co.id/...",
      "retrieved_at": "2026-07-16T00:00:00+00:00",
      "official": true,
      "source_format": "json"
    }
  ],
  "warnings": [],
  "meta": {}
}
```

Credential values are redacted from provenance URLs.

## Tools

- `idx_list_companies`
- `idx_company_profile`
- `idx_company_announcements`
- `idx_financial_reports`
- `idx_filing_facts`
- `bps_list_subjects`
- `bps_list_variables`
- `bps_get_data`
- `ksei_sid_growth`
- `ksei_investor_demographics`
- `source_health`

See [`docs/SOURCES.md`](docs/SOURCES.md) for source contracts and boundaries,
and [`docs/HERMES.md`](docs/HERMES.md) for Hermes registration and live checks.

## Market data (optional, non-official) — via fzn0x/idx

Official IDX market prices are a licensed product, so the official tools above
carry none. For delayed prices and screening, this server can delegate to the
**fzn0x/idx** CLI (`ihsg-cli`, MIT License, Copyright (c) 2026 Midori Research
and idx contributors — full text in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)):

```bash
npm install -g ihsg-cli        # or: cargo install --locked ihsg-cli
# optional: export IDX_CLI_PATH=/path/to/idx
```

No upstream code is copied into this repository; the server invokes the `idx`
binary as a subprocess (`idx -o json ...`) and wraps its output in the same
provenance envelope, with `official: false` and a note that the data is delayed
Yahoo Finance / MSN Money aggregation subject to those providers' terms.

Additional tools when the binary is present:

- `market_quote` — delayed quotes for one or more tickers
- `market_history` — OHLCV candles
- `market_fundamental` — ratios + upstream rule-based verdict (not a recommendation)
- `market_technical` — RSI/MACD/MA/Bollinger/ATR
- `market_screen` — screen ~950 IDX tickers by preset or filter expression
- `market_foreign` — foreign buy/sell per session (idx.co.id summaries)
- `market_overview`, `market_indices` — IHSG and all IDX indices
- `ownership_holders` — KSEI >1% holders (needs a prior `idx ownership sync` on the host)

`source_health` reports the backend as `fzn_idx_market`.

## Install

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
```

Optional BPS setup:

1. Create a key at <https://webapi.bps.go.id/developer/>.
2. Export it as `BPS_API_KEY` or configure it in the MCP client's scoped environment.

Run over stdio:

```bash
.venv/bin/python -m indonesia_data_mcp.server
```

Hermes registration (run from the repository root):

```bash
hermes mcp add indonesia-official \
  --command "$PWD/.venv/bin/python" \
  --args -m indonesia_data_mcp.server
```

If BPS is enabled, add `BPS_API_KEY` to Hermes's secret environment rather than Markdown or command history.

## IDX Research Desk dashboard

Run the responsive evidence-first dashboard on the LAN:

```bash
.venv/bin/pip install -e '.[dashboard]'
.venv/bin/python -m dashboard --host 0.0.0.0 --port 8010
```

Open `http://localhost:8010`. Official issuer, announcement, and filing data is
kept separate from clearly labelled in-memory demo workflow state. The dashboard
does not display unlicensed market prices or investment recommendations.

## Development

```bash
.venv/bin/pytest -q
```

Live tests are separate so upstream availability cannot make the deterministic suite flaky.

### Query official XBRL facts

`idx_filing_facts` resolves the requested IDX filing, downloads its official
`instance.zip`, verifies the ZIP, calculates SHA-256, and exposes its raw XBRL
facts with context periods, dimensions, units, decimals, and citations. Use the
optional `concept` substring to keep responses small—for example, `Assets`,
`ProfitLoss`, or `InterestIncome`.

The tool deliberately preserves the filing's taxonomy and raw values. It does
not claim canonical cross-company normalization: concept names can vary by
issuer profile and taxonomy version.

## Scope and limitations

- IDX's public endpoints are protected by Cloudflare. The client establishes a
  normal IDX session and uses conservative pacing. If ordinary HTTP TLS is
  rejected, it retries with browser-compatible TLS via `curl_cffi`; it does not
  solve or bypass CAPTCHAs.
- This MCP returns official source records and attachments. It can query raw
  `instance.zip` XBRL facts, but canonical cross-company line-item
  normalization remains a separate future layer.
- OJK's public data portal and Bank Indonesia sources were investigated. Their browser-facing services require additional contract discovery and reliability work, so they are not falsely advertised as production-ready tools in v0.1.
- Official market-price data is not included: official IDX real-time/delayed market data is a licensed data product. Delayed, non-official prices are available only through the optional fzn0x/idx backend described above, and are labelled `official: false`.

## License

MIT

TDQS

B3.3/5.0

Scored across 10 tools

Disambiguation5/5

Each tool is clearly scoped to a specific data source (bps_, idx_, ksei_) and a distinct operation (e.g., get_data vs list_subjects). No two tools overlap in purpose; even similar operations like 'list' targets different entities across sources.

Naming Consistency5/5

All tool names follow a consistent snake_case format with a source prefix (bps_, idx_, ksei_) and a descriptive verb_noun pattern. The naming is predictable and unambiguous.

Tool Count5/5

With 10 tools covering three distinct data sources plus a health check, the count is well-balanced. It covers core operations without being overwhelming or too sparse.

Completeness4/5

The tool set covers the main workflows for each data source: listing entities, retrieving details, and fetching data. The BPS tools lack an explicit period listing (implied by get_data parameters), and IDX lacks trading data, but the coverage is reasonable for the stated domain.