# korean-stat-mcp

KOSIS OpenAPI 데이터를 MCP 클라이언트에서 바로 쓸 수 있게 만든 Python 서버입니다.

Claude Desktop, Claude Code, Cursor, Windsurf 같은 MCP 지원 도구에서 통계표를
검색하고, 메타데이터를 확인하고, 데이터를 가져와 간단한 분석까지 이어갈
수 있습니다.

[English README](./README-EN.md)

[![PyPI](https://img.shields.io/pypi/v/korean-stat-mcp)](https://pypi.org/project/korean-stat-mcp/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/seolcoding/korean-stat-mcp/ci.yml?branch=main)](https://github.com/seolcoding/korean-stat-mcp/actions)

## 할 수 있는 일

- KOSIS 통계표 키워드 검색
- 기관/주제별 통계 목록 탐색
- 통계표 분류, 항목, 수록 기간 같은 메타데이터 조회
- 원천 데이터 조회, 필터링, 그룹 집계
- 저장된 데이터 청크 읽기와 원천 데이터 검증
- `verify_statistics`로 특정 수치가 KOSIS 원천 행과 맞는지 확인

KOSIS API는 테이블마다 필요한 파라미터가 조금씩 다르고, 기간/분기/지자체
데이터에서 예외가 자주 나옵니다. 이 서버는 그 부분을 MCP 도구 형태로 감싸서
클라이언트 쪽 설정을 줄이는 데 초점을 둡니다.

## 호스팅 인스턴스로 바로 사용 (설치 없음)

`pip install` 없이, Claude.ai 커넥터에 URL 한 줄만 추가하면 됩니다.
Claude Pro/Max/Team/Enterprise 요금제가 필요합니다 (Free는 커넥터 1개만 가능).

### 0단계: KOSIS API 키 발급 (무료, 1분)

[KOSIS OpenAPI 신청 페이지](https://kosis.kr/openapi/)에서 회원가입 후
"Open API 사용 신청" 버튼을 누르면 인증키가 발급됩니다.

### 커넥터 추가 방법

1. [claude.ai](https://claude.ai)에 로그인합니다.
2. 왼쪽 사이드바 하단의 **본인 이름** → **설정** → **커넥터** 메뉴로 들어갑니다.
3. **커스텀 커넥터 추가** 버튼을 클릭합니다.
4. 아래 내용을 입력합니다 (`<YOUR_KEY>` 를 0단계에서 발급받은 키로 바꿉니다):
   - **이름**: `korean-stat`
   - **URL**: `https://korean-stat-mcp.seolcoding.com/mcp?apiKey=<YOUR_KEY>`
5. **추가** 버튼을 누르면 등록 완료.
6. 추가한 커넥터의 **구성** → 도구 목록에서 모든 도구를 **항상 사용**으로 설정.

### 사용

채팅 화면에서 자연어로 물어보면 `korean-stat` 도구가 자동 호출됩니다:

```
"2020년부터 2023년까지 전국 인구 추이 보여줘"
"서울 자치구별 사업체 수 비교"
```

### 자체 호스팅도 그대로 동작

기존 `pip install` + `KOSIS_API_KEY` 환경변수 방식은 변경 없이 작동합니다. 아래 [설치](#설치) 섹션을 참고하세요.

---

## 설치

먼저 KOSIS OpenAPI 키가 필요합니다. 키는
[KOSIS OpenAPI 신청 페이지](https://kosis.kr/openapi/)에서 발급받을 수 있습니다.

### Claude Desktop / Cursor / Windsurf

```bash
pip install korean-stat-mcp
```

MCP 설정 파일에 아래 내용을 추가합니다.

```json
{
  "mcpServers": {
    "korean-stat": {
      "command": "korean-stat-mcp",
      "env": {
        "KOSIS_API_KEY": "<KOSIS_API_KEY>"
      }
    }
  }
}
```

Claude Desktop의 macOS 설정 파일 위치:

```text
~/Library/Application Support/Claude/claude_desktop_config.json
```

### MCP 클라이언트 설정

```json
{
  "mcpServers": {
    "korean-stat": {
      "command": "korean-stat-mcp",
      "env": {
        "KOSIS_API_KEY": "<KOSIS_API_KEY>"
      }
    }
  }
}
```

### 직접 실행

```bash
pip install korean-stat-mcp
export KOSIS_API_KEY="<KOSIS_API_KEY>"
korean-stat-mcp          # stdio MCP, 로컬 Claude Desktop/Cursor용
korean-stat-mcp --http   # Streamable HTTP 서버, http://localhost:8000/mcp
```

설치 확인:

```bash
korean-stat-mcp --version
```

## 원격 MCP로 호스팅하기

공식 호스팅 엔드포인트:

```text
https://korean-stat-mcp.seolcoding.com/mcp?apiKey=<YOUR_KOSIS_KEY>
```

이 URL을 그대로 Claude.ai 커넥터에 붙이거나 다른 MCP 클라이언트의 Streamable
HTTP endpoint로 사용할 수 있습니다. 자세한 등록 절차는 위
[호스팅 인스턴스로 바로 사용](#호스팅-인스턴스로-바로-사용-설치-없음) 섹션 참고.

상태·메타 확인:

```bash
curl https://korean-stat-mcp.seolcoding.com/health
curl https://korean-stat-mcp.seolcoding.com/info
```

### 자체 호스팅도 가능합니다

본인 KOSIS 키 쿼터를 별도로 분리하고 싶거나, 사내 네트워크/온프레미스 환경에서
운영해야 하면 직접 띄울 수 있습니다. Docker, Fly.io, Render, Railway,
DigitalOcean App Platform, 일반 VPS 배포 가이드는
[deploy/README.md](./deploy/README.md)에 정리되어 있습니다.

```bash
# 직접 띄울 때
KOSIS_API_KEY=<YOUR_KEY> korean-stat-mcp --http
curl https://<your-host>/health
```

## 주요 도구

| 구분 | 도구 | 용도 |
|---|---|---|
| 검색 | `search_statistics` | 키워드로 통계표 찾기 |
| 탐색 | `browse_categories` | 기관/주제별 목록 탐색 |
| 메타데이터 | `get_table_metadata`, `get_available_values` | 분류, 항목, 기간 확인 |
| 데이터 | `get_statistics_data` | KOSIS 원천 데이터 조회 |
| 가공 | `filter_statistics`, `aggregate_statistics` | 필터링, 그룹 집계 |
| 저장 데이터 | `read_stored_data`, `list_stored_data` | 큰 결과를 나눠 읽기 |
| 검증 | `verify_statistics` | 특정 수치와 원천 데이터 대조 |

전체 도구 목록과 이전 이름과의 매핑은
[docs/TOOL_MIGRATION.md](./docs/TOOL_MIGRATION.md)를 참고하세요.

## 환경변수

| 변수 | 필수 | 설명 |
|---|---:|---|
| `KOSIS_API_KEY` | 예 | KOSIS OpenAPI 인증키 |
| `KOSIS_ARTIFACTS_DIR` | 아니오 | 로컬 차트/리포트 저장 경로 |
| `KOSIS_MCP_URL` | 아니오 | 자체 호스팅 인스턴스의 base URL |

전체 예시는 [.env.example](./.env.example)에 있습니다.

## 검증 상태

- Python 3.12 / 3.13 CI를 사용합니다.
- 2026-04-30 기준 unit test는 449개가 통과했습니다.
- KOSIS live pilot 100건에서 API 오류, timeout, parse 오류는 없었습니다.
  `no_data` 2건은 폐기되었거나 응답이 비어 있는 통계표로 분류했습니다.

자세한 내용은 [docs/VALIDATION_REPORT.md](./docs/VALIDATION_REPORT.md)에 있습니다.

## 문서

- [docs/USER_GUIDE.md](./docs/USER_GUIDE.md): 사용자 가이드
- [docs/KOSIS_API_REFERENCE.md](./docs/KOSIS_API_REFERENCE.md): KOSIS API 정리
- [docs/TOOL_MIGRATION.md](./docs/TOOL_MIGRATION.md): 도구 이름 변경/매핑
- [deploy/README.md](./deploy/README.md): 배포 가이드
- [MIGRATION.md](./MIGRATION.md): 기존 `kosis-mcp` 사용자용 변경 사항
- [CONTRIBUTING.md](./CONTRIBUTING.md): 개발 환경과 PR 절차

## 라이선스

코드는 MIT 라이선스로 배포됩니다. KOSIS 데이터 자체의 이용 조건은
[KOSIS 국가통계포털](https://kosis.kr/) 정책을 따릅니다.