ne-kosis-mcp

국가통계포털(KOSIS) OpenAPI를 쓰는 MCP(Model Context Protocol) 서버입니다. 인구, 지역별 학생 수, 사교육비 같은 통계를 찾고(find_table), 조회하고(kosis_data), 추이와 성장률을 계산하고(kosis_trend), 엑셀/CSV로 내보냅니다(kosis_export). 거시 트렌드와 시장 규모 파악이 목적입니다.

구조 참고: 설정, 캐시, 도구 허용 목록, 내보내기 구조는 ne-naver-api-mcp(원본: isnow890/naver-search-mcp, MIT License)에서 가져왔습니다. 원본의 저작권 고지는 LICENSE에 그대로 유지됩니다.

상태

• 키 없이 검증한 것: 단위 테스트(가짜 응답), 기간 분할, 수치 파싱, 증감률·CAGR 계산, 카탈로그 검색, 서버 도구 등록.

• 실제 KOSIS 호출로 아직 검증하지 못한 것: 응답 구조, 오류 형식(err/errMsg), 메타(getMeta ITM/OBJ) 응답 키, 반기 코드(H vs S), parentListId/parentId 중 맞는 이름. KOSIS 문서에 샘플 응답이 없어 추정으로 구현했습니다. 키를 넣고 KOSIS_LIVE_TEST=1 uv run pytest tests/live로 확인하세요.

• 카탈로그(data/catalog.json)는 비어 있습니다. 통계표 ID를 기억에 의존해 적으면 틀린 값이 들어갈 수 있어서, 키로 실제 호출해 검증한 표만 넣기로 했습니다. 아래 "카탈로그 채우기"를 보세요. 그전에는 find_table이 KOSIS 통합검색으로 대신합니다.

Related MCP server: Korea Stats MCP

도구 (7개)

권장 흐름: find_table → kosis_table_meta → kosis_data 또는 kosis_trend → kosis_export.

설치

필요한 것: uv, KOSIS 인증키(https://kosis.kr/openapi 로그인 후 활용신청).

claude mcp add ne-kosis -s user ^
  -e KOSIS_API_KEY=발급키 ^
  -e KOSIS_EXPORT_DIR=C:\Users\내이름\Documents\kosis-exports ^
  -- uvx --from D:\repos\ne-kosis-mcp ne-kosis-mcp

(줄 끝 ^는 Windows cmd의 줄 이음입니다.) 개발 중에는 이 폴더의 .env에 KOSIS_API_KEY=...를 넣으면 서버가 읽습니다(.env는 git에 올라가지 않습니다).

환경변수

카탈로그

src/ne_kosis_mcp/data/catalog.json은 사람이 확인한 통계표 목록입니다. 항목 하나의 형식:

{
  "id": "student-count-by-region",
  "orgId": "...", "tblId": "...",
  "title": "표 이름",
  "topic": "교육 > 학생 수",
  "description": "무엇을 재는지, 어떤 질문에 답하는지",
  "prdSe": "Y", "period": "1990~2024",
  "unit": "명",
  "items": [{"id": "T1", "name": "학생수"}],
  "classifications": [{"level": 1, "name": "시도", "note": "ALL이면 전체 시도"}],
  "keywords": ["학생 수", "초등학생", "학령인구"],
  "notes": ["2021년부터 조사 기준 변경"],
  "verified": "YYYY-MM-DD"
}

find_table은 keywords(가중치 최고), title, topic, description 순으로 점수를 매깁니다.

카탈로그 채우기

키가 있으면 uv run python scripts/build_catalog.py "학생수" "사교육비" ...로 주제별 후보를 KOSIS 통합검색과 메타 조회로 모아 catalog.draft.json에 씁니다. 후보를 사람이 확인(실제 kosis_data 호출로 값 확인)하고 설명·키워드·주의사항을 채워 catalog.json에 옮깁니다.

한계

• ELT 시장 규모처럼 KOSIS에 직접 없는 지표는 대리 지표(영어 사교육비, 학원업 사업체·매출, 학령인구 등)로 추정해야 합니다. 도구는 통계표의 값만 돌려주며 시장 규모를 추정하지 않습니다.

• 통계표마다 단위와 조사 기준이 다릅니다. 모든 결과에 limitations가 붙습니다.

• 기간 자동 분할은 연/반기/분기/월 주기와 시작·종료 지정일 때만 됩니다 (일 주기, 최근 N개는 범위를 직접 좁혀야 합니다).

개발

uv sync
uv run pytest