Kosis Openapi MCP server

kosis-openapi-mcp

<!-- mcp-name: io.github.rubatoyd/kosis-openapi-mcp -->

<!-- usage:start -->

📈 사용량 — 최근 14일 조회 0회(고유 0) · 클론 0회(고유 0) · 릴리스 자산 누적 다운로드 31

2026-09-22 자동 갱신 · 전체 이력은 docs/usage.csv. GitHub 트래픽 통계는 14일 창만 제공하므로 이 저장소가 매일 찍어 누적한다.

<!-- usage:end -->

KOSIS(국가통계포털) 공유서비스 OpenAPI 를 검색·수집하는 MCP 서버 + CLI.

통계표를 찾고, 항목·분류·주기를 확인하고, 수치를 받아 xlsx·csv·json·sqlite 로 내보낸다. 4만 셀 제한에 걸리면 기간을 알아서 쪼개 전수를 회수한다.

자매 저장소: law-openapi-mcp(법제처) · na-openapi-mcp(국회도서관) · nl-openapi-mcp(국립중앙도서관) · kci-openapi-mcp · scienceON-mcp

무엇을 돌려주나

통계 그 자체다. 표의 메타(작성기관·조사명·수록기간·주기)와 수치(시점 × 분류 × 항목 → 값)를 도메인 그대로 준다.

서지·인용 형식은 부가 기능(kosis_citation)으로 따로 두었다. 서지관리 도구로 넘길 때만 쓰면 되고, 그 도구가 아는 유형 목록이 통계 응답의 모양을 바꾸지는 않는다.

준비물

인증키 하나. kosis.kr 회원가입 후 공유서비스 활용신청(자동 승인).

cp .env.example .env    # KOSIS_API_KEY=... 를 채운다

🔴 발급된 값을 그대로 넣으세요. base64 처럼 보여도(끝이 =) 디코드하면

err 11(유효하지 않은 인증키)이 납니다.

설치·실행

uv sync
uv run kosis status
uv run kosis search 사교육비
uv run kosis meta --org 101 --tbl DT_1PE201 --kind ITM     # 항목 ID 확인
uv run kosis data --org 101 --tbl DT_1PE201 --prd Y --start 2020 --end 2025
uv run kosis collect --org 101 --tbl DT_1B040A3 --prd M --start 202101 --end 202512
# 분류축이 여럿인 표도 그대로 — 축 개수는 알아서 맞춘다(산업 × 규모)
uv run kosis data --org 118 --tbl DT_118N_MON051 --prd H --start 202401 --end 202401
# 주요지표(통계표와 다른 계열) — 표 구조를 몰라도 값까지 바로
uv run kosis indicator 출산율
uv run kosis indicator-data --id 13 --start 2020 --end 2025

MCP 등록:

{
  "mcpServers": {
    "kosis": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/rubatoyd/kosis-openapi-mcp", "kosis-mcp"],
      "env": { "KOSIS_API_KEY": "발급받은_값_그대로" }
    }
  }
}

PyPI 에 올린 패키지가 아직 없어 저장소에서 바로 받아 쓴다(자매 저장소와 같은 방식).

main 의 HEAD 를 쓰므로 다음 기동에 최신이 반영된다.

MCP 도구

알아 둘 것 (전부 실측)

172쪽짜리 공식 개발가이드가 있는데도 가장 중요한 셋이 그 안에 없거나 틀리다:

리터럴이 온다. 이 파라미터는 가이드의 입력 변수 표에 없고 JSP 예제 안에만 있다.

• 🔴 jsonVD=Y 가 없으면 JSON 이 아니다 — 키에 따옴표가 없는 자바스크립트 객체

를 써야 한다. 가이드가 표를 실어 둔 statisticsData.do 로 보내면 항상 err 20.

• 🔴 통계자료를 orgId/tblId 로 부르려면 /openapi/Param/statisticsParameterData.do

• 🔴 인증키를 디코드하지 말 것.

그 밖에:

Shortened. The full README is on GitHub.