Korean Stats MCP

국가데이터처 KOSIS, 이제 사이트에 들어가지 않습니다. AI 어시스턴트에게 한국어로 물어보면 국가데이터처 공식 수치가 출처와 함께 바로 나옵니다.

국가데이터처 KOSIS OpenAPI 기반 MCP 서버 (Python FastMCP). Claude Desktop·Cursor 등에서 stdio 또는 HTTP로 사용.

30초 만에 겪어보기

채팅창에 이렇게 칩니다 (Claude.ai 커넥터 등록 후 — 아래 설치법 참고)

나: 광진구 고용률 알려줘

AI: 2025년 하반기 광진구의 고용률은 61.6%입니다.
    📊 출처: 고용률 (KOSIS DT_1ES3A03_A01S)

KOSIS 사이트에 들어가 통계표를 찾고 → 분류 코드를 고르고 → 자치구 행을 스크롤할 필요가 없습니다. 자치구 이름과 궁금한 것만 한국어로 던지면 됩니다.

공무원 업무, 이렇게 바뀝니다

국가데이터처 통계는 KOSIS에 다 있습니다. 문제는 꺼내 쓰는 비용입니다. 통계표 ID를 모르면 검색에서 헤매고, 찾아도 분류·항목·주기 코드를 조립해야 하고, 자치구 단위는 표 안에서 행을 뒤져야 합니다. 그래서 보고서 마감 직전마다 KOSIS와 씨름합니다.

이 도구는 그 과정을 자연어 한 줄로 줄입니다. 실제 업무 장면으로 봅니다.

📋 시정연설·신년사·업무보고 — 30분이 5초로

상황 — 시장 신년사 원고에 "우리 시 현황" 한 단락을 넣어야 한다. 인구·출산율·고용·지역경제 수치를 KOSIS에서 하나씩 베껴오는 데 매번 30분~1시간.

나: 성남시 신년사에 넣을 핵심 통계 한 줄로 정리해줘

AI: 성남시의 주민등록 인구 ○○만 명, 합계출산율 ○.○○명,
    65세 이상 고령인구 ○○만 명, 실업률 ○.○%, 지역내총생산 ○○조 원
    (○○○○년 기준)입니다.

chain_region_brief의 연설용 한 줄 모드가 핵심 지표를 자동으로 추려 한 문장으로 만듭니다. 13개 지표 전체 브리핑도 한 번에 가능합니다.

🏛 지방의회 답변·행정사무감사 대비 — "옆 동네보다 낮은 거 아니냐"

상황 — 의원이 "우리 구 실업률이 인접 구보다 높은 것 아니냐"고 질의할 예정. 인접 자치구를 일일이 조회해 비교표를 만들어야 한다.

나: 강남구, 서초구, 송파구 실업률이랑 고용률 비교해줘

AI: 📊 3개 지역 × 2개 지표 비교
    • 실업률: 최고 ○○구(○.○%), 최저 ○○구(○.○%)
    • 고용률: 최고 ○○구(○○.○%), 최저 ○○구(○○.○%)
    [지역별 순위 매트릭스 + 기준시점 포함]

chain_compare_regions는 최대 17개 지역 × 8개 지표를 한 번에 매트릭스로 만들고 지표별 순위까지 매깁니다. "전국 17개 시도 출산율 순위"도 한 줄입니다.

📑 정책보고서·연구용역 현황 분석 — 10년 추세를 한 번에

상황 — 저출산 대응 5개년 계획 보고서. "최근 10년 추세" 챕터에 들어갈 시계열 데이터가 필요하다.

나: 저출산 영역 최근 10년 추세 정리해줘

AI: 📑 저출산 영역 10년 추세
    • 합계출산율: 지속 하락 (20○○→20○○년, -○○%)
    • 출생아수: 지속 하락 (-○○%)
    • 혼인건수: 지속 하락 (-○○%)
    • 평균초혼연령: 상승 (+○.○세)
    [연도별 데이터포인트 + 변화율 전체]

chain_policy_indicator는 7개 정책 영역(저출산·고령화·주거·일자리·치안·보건·경제)을 영역별 3~4개 지표 묶음으로 시계열 분석합니다. 평균 변화율·최고/최저점·추세 분류가 함께 나옵니다.

🗣 민원 응대·보도자료 — 묻는 즉시 공식 수치

상황 — "우리 동네 미세먼지가 요즘 어떠냐"는 민원 전화. 또는 보도자료에 들어갈 수치를 30분 뒤 회신해야 한다.

나: 충남 미세먼지 수치
AI: 20○○년 충남의 PM2.5 농도는 ○○㎍/㎥입니다. 📊 출처: KOSIS

나: 부산 인구 최근 10년 변화는?
AI: 부산의 인구 10년 추세: 지속적인 하락 추세. ... (변화율·최고/최저점 포함)

단일 수치는 quick_stats, 추세는 quick_trend. 모든 응답에 통계표 출처가 붙어 그대로 인용할 수 있습니다.

🎯 자치구·시군 단위까지 — 광역 평균에 묻히지 않습니다

상황 — "광진구" 고용률이 필요한데 검색하면 늘 "서울특별시" 평균만 나온다.

나: 광진구 고용률, 광진구 65세 이상 인구

AI: 2025년 하반기 광진구의 고용률은 61.6%입니다.
    2024년 광진구의 65세 이상 고령인구는 ○○,○○○명입니다.

전국 230개 이상의 자치구·시군을 KOSIS 자치구 단위 통계표로 직접 조회합니다. 전국 226개 시군구가 동일 구조로 수록된 KOSIS 표준 통계표(자치구 코드 라우팅)를 우선 쓰고, 표준표에 없는 분야만 자치구 통계연보(.xlsx)로 보완합니다. 중구·남구처럼 여러 시에 있는 이름도 "부산 중구"처럼 광역시를 같이 말하면 정확히 구분합니다.

🛡 ChatGPT가 찍어준 통계, 그대로 보고서에 넣지 마세요

일반 AI는 통계 수치를 학습 시점 기준으로 기억합니다. "서울 인구"를 물으면 몇 년 전 값을 자신 있게 답합니다. 그 수치가 보고서·연설문·국정감사 자료에 들어가면 사고입니다.

이 커넥터를 켜면 AI는 질문할 때마다 KOSIS 공식 DB를 실시간 조회하고, 답변에 통계표 ID(출처)를 함께 표기합니다. 추정이 아니라 인용입니다.

장래추계가 포함된 통계는 "이 수치는 실측이 아닌 국가데이터처 추계"라는 안내가, 인구동향(출생·사망·혼인·이혼) 최근 시점에는 "잠정치일 수 있음" 안내가 자동으로 붙습니다. 추계·잠정치를 확정 실측처럼 인용하는 실수를 막습니다.

무엇을 물어볼 수 있나

통계 키워드 — 92개 + 자연어 별칭 100개 이상

정식 용어를 몰라도 됩니다. 집값→주택매매가격, 노인→고령인구, 월소득→월평균임금처럼 줄임말·구어체를 자동 변환합니다. 출산률·고용율 같은 률/율 오타, G D P 같은 공백, population·gdp 같은 영문도 인식합니다.

정의가 다른 지표는 조용히 바꿔치지 않습니다 — 청년실업률(15~29세)·연봉(연 단위)·가계소득처럼 비슷해 보여도 다른 통계인 질문에는 오답 대신 "어느 통계를 봐야 하는지" 안내가 나갑니다. 지역명도 마찬가지 — 인식 못 한 지역명에 전국값을 대신 내놓지 않습니다.

지역 — 17개 시도 + 자치구·시군 230개 이상

전국 광역시도 17개(풀네임·약칭 모두)와 자치구·시군 230여 곳. "민선 8기 출산율 추이", "임기 4년차 GRDP", "작년 대비 실업률", "역대 인구" 같은 한국 행정 어법의 기간 표현도 자동으로 분석 연수로 환산합니다.

14개 도구

대부분의 질문은 quick_stats·quick_trend·quick_rank·체인 도구 3종이면 끝납니다. 나머지는 정밀 조회용입니다.

설치

방법 1 — 로컬 stdio (Claude Desktop / Cursor)

준비물: Python 3.11+ · KOSIS OpenAPI 키 (무료)

git clone https://github.com/chrisryugj/korean-stats-mcp.git
cd korean-stats-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

{
  "mcpServers": {
    "korean-stats": {
      "command": "/절대경로/korean-stats-mcp/.venv/bin/korean-stats-mcp",
      "args": [],
      "env": { "KOSIS_API_KEY": "발급받은_키" }
    }
  }
}

원클릭 등록:

export KOSIS_API_KEY=발급받은_키
# PATH에 korean-stats-mcp 가 있어야 함 (.venv/bin 활성화 후)
bash install.sh --client cursor

프로젝트 루트 .env에 KOSIS_API_KEY=...를 넣어도 됩니다 (.env.example 참고).

방법 2 — Docker Compose (서버 배포)

cp .env.example .env   # KOSIS_API_KEY 설정
docker compose up -d --build

• MCP: POST /mcp (기본 :3000)

• 헬스: GET /health

• Redis: compose 내부 네트워크 (REDIS_URL=redis://redis:6379/0)

방법 3 — Vercel (서버리스 HTTP)

cp .env.example .env   # 로컬 vercel dev용
npx vercel login
npx vercel env add KOSIS_API_KEY      # production + preview
npx vercel env add MCP_AUTH_TOKEN     # (권장) Bearer 인증
npx vercel --prod

• MCP: POST https://<your-project>.vercel.app/mcp

• 헬스: GET /health

• Redis: Upstash Redis 연동 후 REDIS_URL 설정 (미설정 시 인메모리 캐시)

• Cursor 연결:

{
  "mcpServers": {
    "korean-stats": {
      "url": "https://<your-project>.vercel.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN" }
    }
  }
}

로컬에서 HTTP만 띄울 때:

KOSIS_API_KEY=... korean-stats-mcp --http --port 3000

정확성과 신뢰

• 공식 출처 — 모든 수치는 국가데이터처 KOSIS OpenAPI를 실시간 조회합니다. 응답에 통계표 ID가 표기되어 그대로 인용·검증할 수 있습니다.

• 추계 데이터 구분 — 장래추계가 포함된 통계는 "추계" 안내가 자동으로 붙습니다.

• 자치구 데이터 무결성 — 자치구 단위 데이터가 KOSIS에 없으면 임의로 광역시도 값을 자치구 값인 척 답하지 않고, "광역시도 데이터로 대체했다"고 명시합니다.

• 캐시 — 동일 질의는 6시간 캐싱하여 빠르게 응답하되, 통계 갱신 주기를 해치지 않습니다.

변경 이력

• TypeScript/Node MCP → Python FastMCP 3.4.7 전면 포팅

• npm / gomdori 통합 호스트 의존 제거 — 독립 stdio + Streamable HTTP

• 엑셀 파싱: kordoc → openpyxl 마크다운 변환

• 14개 도구·2개 리소스·1개 프롬프트 유지

라이선스

MIT

참고한 프로젝트

• Dayoooun/korea-stats-mcp — 이 프로젝트의 포크 시작점. 원본에 깊은 감사를 표합니다. 라이선스는 원본과 동일한 MIT.

• FastMCP — Python MCP 서버 프레임워크.