Korean Stat Mcp

korean-stat-mcp

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

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

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

[](https://pypi.org/project/korean-stat-mcp/) [](https://www.python.org/) [](./LICENSE) [](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 신청 페이지에서 회원가입 후 "Open API 사용 신청" 버튼을 누르면 인증키가 발급됩니다.

커넥터 추가 방법

1. claude.ai에 로그인합니다.
2. 왼쪽 사이드바 하단의 본인 이름 → 설정 → 커넥터 메뉴로 들어갑니다.
3. 커스텀 커넥터 추가 버튼을 클릭합니다.
4. 아래 내용을 입력합니다 (`` 를 0단계에서 발급받은 키로 바꿉니다):

• 이름: korean-stat
• URL: https://korean-stat-mcp.seolcoding.com/mcp?apiKey=

1. 추가 버튼을 누르면 등록 완료.
2. 추가한 커넥터의 구성 → 도구 목록에서 모든 도구를 항상 사용으로 설정.

사용

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

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

자체 호스팅도 그대로 동작

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

---

설치

먼저 KOSIS OpenAPI 키가 필요합니다. 키는 KOSIS OpenAPI 신청 페이지에서 발급받을 수 있습니다.

Claude Desktop / Cursor / Windsurf

pip install korean-stat-mcp

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

{
  "mcpServers": {
    "korean-stat": {
      "command": "korean-stat-mcp",
      "env": {
        "KOSIS_API_KEY": ""
      }
    }
  }
}

Claude Desktop의 macOS 설정 파일 위치:

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

MCP 클라이언트 설정

{
  "mcpServers": {
    "korean-stat": {
      "command": "korean-stat-mcp",
      "env": {
        "KOSIS_API_KEY": ""
      }
    }
  }
}

직접 실행

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

설치 확인:

korean-stat-mcp --version

원격 MCP로 호스팅하기

공식 호스팅 엔드포인트:

https://korean-stat-mcp.seolcoding.com/mcp?apiKey=

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

상태·메타 확인:

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)에 정리되어 있습니다.

# 직접 띄울 때
KOSIS_API_KEY= korean-stat-mcp --http
curl https:///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/TOOLMIGRATION.md](./docs/TOOLMIGRATION.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/VALIDATIONREPORT.md](./docs/VALIDATIONREPORT.md)에 있습니다.

문서

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

라이선스

코드는 MIT 라이선스로 배포됩니다. KOSIS 데이터 자체의 이용 조건은 KOSIS 국가통계포털 정책을 따릅니다.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: seolcoding
• Source: seolcoding/korean-stat-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.