# ko-stock-mcp

An MCP server that exposes Korean **DART (전자공시시스템, Financial Supervisory Service
electronic disclosure)** data to MCP clients such as Claude Desktop.

> 한국어 문서는 [README.ko.md](./README.ko.md)를 참고하세요.

## Tools

Both DART (electronic disclosure) and KRX (Korea Exchange) tools are provided.

### DART (disclosure)

| Tool | Description |
|------|-------------|
| `get_corp_code` | Look up a company's DART corp_code (8-digit) by name or stock code (6-digit). Entry point for the other tools. |
| `get_company_info` | Company profile (name, CEO, market class, industry, incorporation date, etc.). |
| `get_disclosure_list` | Search disclosures by company / date range / disclosure type. |
| `get_disclosure` | Fetch a disclosure's original document. Large docs return a table of contents (`toc`); drill in with `section_id`. |
| `get_financial_statement` | XBRL financial statements (BS / IS / CIS / SCE / CF) from periodic reports. |
| `get_today_date` | Today's date in KST/UTC (`YYYYMMDD` + ISO). |

### KRX (Korea Exchange) — requires `KRX_API_KEY`

| Tool | Description |
|------|-------------|
| `get_market_type` | Determine which market (KOSPI/KOSDAQ/KONEX) a stock code belongs to. Uses DART corp class first, falls back to KRX. |
| `get_stock_trade_info` | Daily trading data for a business day (close, change rate, volume, market cap, etc.). |
| `get_stock_base_info` | Stock base info (name, standard/short code, listing date, par value, shares outstanding, etc.). |

Typical flow — disclosures/financials: `get_corp_code` → (`get_disclosure_list` |
`get_financial_statement` | `get_company_info`) → `get_disclosure` for full text. Market data:
(optionally `get_market_type` →) `get_stock_trade_info` | `get_stock_base_info` (`bas_dd`
must be a business day; non-trading days return empty).

> KRX tools return a friendly error when `KRX_API_KEY` is unset; DART features are unaffected.
> Note `get_market_type` works with just the DART key (via corp class).

#### KRX response fields

`get_stock_trade_info` / `get_stock_base_info` return the raw KRX fields verbatim under
`result` (amounts/quantities are strings, dates are `YYYYMMDD`).

**`get_stock_trade_info` (daily trading data)**

| Field | Meaning |
|-------|---------|
| `BAS_DD` | Base date (YYYYMMDD) |
| `ISU_CD` | Stock code (6-digit short code in this response) |
| `ISU_NM` | Stock name |
| `MKT_NM` | Market (KOSPI/KOSDAQ/KONEX) |
| `SECT_TP_NM` | Section/board |
| `TDD_CLSPRC` | Closing price |
| `CMPPREVDD_PRC` | Change vs. previous day |
| `FLUC_RT` | Change rate (%) |
| `TDD_OPNPRC` / `TDD_HGPRC` / `TDD_LWPRC` | Open / High / Low |
| `ACC_TRDVOL` | Accumulated trading volume (shares) |
| `ACC_TRDVAL` | Accumulated trading value (KRW) |
| `MKTCAP` | Market capitalization (KRW) |
| `LIST_SHRS` | Listed shares |

**`get_stock_base_info` (stock base info)**

| Field | Meaning |
|-------|---------|
| `ISU_CD` | Standard code (12-digit, e.g. KR7005930003) |
| `ISU_SRT_CD` | Short code (6-digit, e.g. 005930) |
| `ISU_NM` | Full stock name |
| `ISU_ABBRV` | Abbreviated name |
| `ISU_ENG_NM` | English name |
| `LIST_DD` | Listing date (YYYYMMDD) |
| `MKT_TP_NM` | Market (KOSPI/KOSDAQ/KONEX) |
| `SECUGRP_NM` | Security group (e.g. common stock) |
| `SECT_TP_NM` | Section/board |
| `KIND_STKCERT_TP_NM` | Share type (e.g. ordinary) |
| `PARVAL` | Par value |
| `LIST_SHRS` | Listed shares |

`get_market_type` returns `{ "market": "KOSPI"|"KOSDAQ"|"KONEX", "source": "dart"|"krx"|"cache" }`
(`source` is where the classification came from).

## Requirements

- Python >= 3.10
- [`uv`](https://docs.astral.sh/uv/)
- A DART Open API key — sign up at <https://opendart.fss.or.kr> (free, instant).
- (Optional) A KRX Open API key — sign up at <https://openapi.krx.co.kr>, request a key, then
  apply for the **six stock services** (3 daily-trade + 3 base-info); approval takes ~1 day.
  Only needed for the KRX market-data tools.

## Setup

```bash
uv sync
cp .env.example .env   # then put your DART_API_KEY in .env
```

## Run / develop

```bash
# Launch the MCP Inspector for local testing
uv run mcp dev src/ko_stock_mcp/server.py

# Or run the server directly (stdio)
uv run ko-stock-mcp
```

## Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ko-stock-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ko-stock-mcp", "run", "python", "-m", "ko_stock_mcp.server"]
    }
  }
}
```

`uv --directory` runs the server with this project as the working directory, so `.env`
(with `DART_API_KEY`, and optionally `KRX_API_KEY`) is loaded automatically — no need to
duplicate the keys here. If you prefer, you can instead pass them explicitly:

```json
"env": { "DART_API_KEY": "<YOUR_DART_API_KEY>", "KRX_API_KEY": "<YOUR_KRX_API_KEY>" }
```

On macOS the config lives at
`~/Library/Application Support/Claude/claude_desktop_config.json`. Restart Claude Desktop
after editing.

## License

MIT — see [LICENSE](./LICENSE).