# opendart-fss-mcp

![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue)

[한국어](README.ko.md)

MCP server for Korea's DART (Financial Supervisory Service) corporate disclosure API.

## What is OpenDART?

[DART (Data Analysis, Retrieval and Transfer System)](https://dart.fss.or.kr) is Korea's equivalent of the SEC's EDGAR system. It is the official electronic disclosure system operated by the Financial Supervisory Service (FSS) where all Korean corporations submit their financial reports, major event disclosures, and shareholding information.

[OpenDART](https://opendart.fss.or.kr) provides a public API to access this data programmatically.

## Features

- **85 tools** covering 7 categories — disclosure search, financial statements, periodic reports, shareholding, major events, securities registration, and utilities
- Runs as a **stdio** or **HTTP (Streamable HTTP)** MCP server
- Works with **Claude Desktop**, **Claude Code**, and any MCP-compatible client
- **Smart company search** — 6-tier search with Korean initial consonant (chosung) matching and fuzzy typo correction
  - `"삼성전자"` exact match, `"삼성"` prefix, `"전자"` substring
  - `"ㅅㅅㅈㅈ"` chosung → 삼성전자, `"ㅅㅅSDI"` mixed → 삼성SDI
  - `"삼선전자"` fuzzy → 삼성전자
- Built on [FastMCP](https://github.com/jlowin/fastmcp) and [opendart-fss](https://github.com/hypn4/opendart-fss-python) SDK

## Prerequisites

- **Python 3.14+**
- **[uv](https://docs.astral.sh/uv/)** (recommended package manager)
- **OpenDART API Key** — get one free at [opendart.fss.or.kr](https://opendart.fss.or.kr)

## Installation

```bash
uv pip install opendart-fss-mcp
```

Or install from source:

```bash
git clone https://github.com/hypn4/opendart-fss-mcp.git
cd opendart-fss-mcp
uv sync
```

## Configuration

Copy `.env.example` to `.env` and set your values:

```bash
cp .env.example .env
```

| Variable | Description | Default |
|---|---|---|
| `OPENDART_API_KEY` | OpenDART API key (**required**) | — |
| `OPENDART_MCP_TRANSPORT` | Transport protocol: `stdio` \| `http` | `stdio` |
| `OPENDART_MCP_HOST` | HTTP bind address | `127.0.0.1` |
| `OPENDART_MCP_PORT` | HTTP port | `8000` |
| `OPENDART_MCP_LOG_LEVEL` | Log level: `DEBUG` \| `INFO` \| `WARNING` \| `ERROR` \| `CRITICAL` | `INFO` |

## Usage

### Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

**From PyPI:**

```json
{
  "mcpServers": {
    "opendart": {
      "command": "uvx",
      "args": [
        "--from", "opendart-fss-mcp",
        "opendart-mcp"
      ],
      "env": {
        "OPENDART_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

**From source:**

```json
{
  "mcpServers": {
    "opendart": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/opendart-fss-mcp",
        "opendart-mcp"
      ],
      "env": {
        "OPENDART_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Claude Code

**From PyPI:**

```bash
claude mcp add opendart -e OPENDART_API_KEY=your_api_key_here -- uvx --from opendart-fss-mcp opendart-mcp
```

**From source:**

```bash
claude mcp add opendart -e OPENDART_API_KEY=your_api_key_here -- uv run --directory /path/to/opendart-fss-mcp opendart-mcp
```

### CLI

```bash
# stdio mode (default)
opendart-mcp

# HTTP mode
opendart-mcp --transport http --host 127.0.0.1 --port 8000
```

### FastMCP

```bash
fastmcp run src/opendart_fss_mcp/server.py:mcp
```

### Example Prompts

> Show me Samsung Electronics' 2024 consolidated financial statements

> Compare revenue and operating profit for Samsung, SK Hynix, and LG Electronics in 2023

> Who are the largest shareholders of Hyundai Motor?

> What dividends did Samsung pay last year?

> Search for M&A-related disclosures from January to June 2024

> Has Samsung announced any convertible bond issuances recently?

> Show me the executive compensation for POSCO Holdings

> What is the auditor's opinion on Kakao's financial statements?

## Available Tools

85 tools organized into 7 categories:

| Category | Prefix | Tools | Description |
|---|---|---|---|
| Disclosure | `disclosure_` | 5 | Company search, disclosure list, document viewer |
| Financial | `financial_` | 7 | Financial statements (single/multi account, XBRL) |
| Report | `report_` | 28 | Periodic report key items (compensation, capital, directors, etc.) |
| Shareholding | `shareholder_` | 2 | Major shareholder and executive holdings |
| Major Events | `event_` | 36 | M&A, capital changes, stock events, lawsuits, and more |
| Registration | `registration_` | 6 | Securities registration statement details |
| Utility | `utility_` | 1 | Current date/time (KST) |

## Development

```bash
# Install dev dependencies
uv sync

# Run tests
uv run pytest

# Lint & format
uv run ruff check .
uv run ruff format .

# Type check
uv run pyright
```

## License

MIT

## Links

- [OpenDART](https://opendart.fss.or.kr) — Official OpenDART API portal
- [DART](https://dart.fss.or.kr) — Electronic Disclosure System
- [opendart-fss](https://github.com/hypn4/opendart-fss-python) — Python SDK for OpenDART API