korean-stat-mcp

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

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

English README

할 수 있는 일

• 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. 아래 내용을 입력합니다 (<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 신청 페이지에서 발급받을 수 있습니다.

Claude Desktop / Cursor / Windsurf

pip install korean-stat-mcp

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

{
  "mcpServers": {
    "korean-stat": {
      "command": "korean-stat-mcp",
      "env": {
        "KOSIS_API_KEY": "<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": "<KOSIS_API_KEY>"
      }
    }
  }
}

직접 실행

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

설치 확인:

korean-stat-mcp --version

원격 MCP로 호스팅하기

공식 호스팅 엔드포인트:

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

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

# 직접 띄울 때
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를 참고하세요.

환경변수

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

전체 예시는 .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/USER_GUIDE.md: 사용자 가이드
• docs/KOSIS_API_REFERENCE.md: KOSIS API 정리
• docs/TOOL_MIGRATION.md: 도구 이름 변경/매핑
• deploy/README.md: 배포 가이드
• MIGRATION.md: 기존 kosis-mcp 사용자용 변경 사항
• CONTRIBUTING.md: 개발 환경과 PR 절차

라이선스

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