🇰🇷 Korea Stats MCP

자연어로 KOSIS 통계를 조회하는 MCP 서버

통계청 KOSIS OpenAPI 기반의 MCP(Model Context Protocol) 서버입니다. Claude, Cursor, Windsurf 등 AI 도구에서 자연어로 한국 통계 데이터를 검색하고 분석할 수 있습니다.

🌐 원격 서버 URL: https://korea-stats-mcp-yxup.vercel.app/mcp

🎯 왜 만들었나요?

AI에게 "한국 인구가 몇 명이야?" 라고 물으면, AI는 학습 데이터의 오래된 정보를 답합니다. Korea Stats MCP를 연결하면 실시간 공식 통계를 조회해서 정확한 답변을 제공합니다.

| Before (MCP 없이) | After (Korea Stats MCP 연결) | |-------------------|------------------------------| | Q: 한국 인구가 몇 명이야? | Q: 한국 인구가 몇 명이야? | | A: 2023년 기준 약 5,100만 명입니다. ❌ | A: 2024년 한국의 총인구는 51,712,619명입니다. ✅ |

✨ 주요 기능

| 기능 | 설명 | |------|------| | ⚡ 빠른 조회 | "실업률", "GDP", "출산율", "미세먼지" 등 83개 키워드 즉시 조회 | | 📈 추세 분석 | 최근 N년간 데이터 추이 및 변화율 분석 | | 🔍 통계 검색 | KOSIS 90만+ 통계표에서 키워드 검색 | | 📊 비교 분석 | 연도별, 지역별, 항목별 통계 비교 | | 🗺️ 지역별 조회 | 17개 시도별 통계 조회 지원 |

🚀 사용 방법

방법 1: 원격 서버 사용 (설치 없이 바로 사용) ⭐ 권장

설치 없이 원격 MCP 서버에 바로 연결할 수 있습니다.

Claude Desktop

claude_desktop_config.json 파일 위치:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "korea-stats": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://korea-stats-mcp-yxup.vercel.app/mcp"
      ]
    }
  }
}

Cursor

설정 → MCP → Add new MCP server:

{
  "korea-stats": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://korea-stats-mcp-yxup.vercel.app/mcp"
    ]
  }
}

Windsurf

MCP 설정에 추가:

{
  "korea-stats": {
    "serverUrl": "https://korea-stats-mcp-yxup.vercel.app/mcp"
  }
}

방법 2: 로컬 설치

직접 서버를 실행하고 싶다면 로컬에 설치할 수 있습니다.

1단계: 설치

# 저장소 클론
git clone https://github.com/Dayoooun/korea-stats-mcp.git
cd korea-stats-mcp

# 의존성 설치 (pnpm 권장)
pnpm install

# 빌드
pnpm run build

2단계: AI 도구에 연결

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "korea-stats": {
      "command": "node",
      "args": ["/절대경로/korea-stats-mcp/dist/index.js"]
    }
  }
}

Cursor (설정 → MCP Servers):

{
  "korea-stats": {
    "command": "node",
    "args": ["/절대경로/korea-stats-mcp/dist/index.js"]
  }
}

방법 3: Kakao PlayMCP

Kakao PlayMCP에서도 사용할 수 있습니다.

PlayMCP 사이트 접속
korea-stats-mcp 검색
클릭 한 번으로 연결 완료!

💬 사용 예시

연결 후 AI에게 자연어로 질문하세요:

"한국 인구가 몇 명이야?"
"서울 실업률 알려줘"
"최근 10년 출산율 추이 보여줘"
"GDP 성장률은?"
"부산과 대구 인구 비교해줘"
"서울 아파트가격 알려줘"
"경기도 GRDP 얼마야?"
"평균 임금 알려줘"
"2024년 10월 출생아수 알려줘"   # 월별 데이터
"서울 전세가격"                # 🆕 전세
"경기 자동차 등록대수"          # 🆕 자동차
"부산 범죄율"                  # 🆕 범죄
"외래관광객 몇 명이야?"
"교통사고 발생건수"            # 🆕 교통사고
"서울 의사수 알려줘"           # 🆕 의료

실제 응답 예시:

✅ "2025년 한국의 주민등록 총인구는 51,117,378명입니다."
✅ "2024년 서울의 실업률은 3%입니다."
✅ "2025년 3월 서울의 아파트매매가격지수는 99.687 (2021.6=100)입니다."
✅ "2025년 한국의 상용근로자 월평균 임금은 4,094,615원입니다."
✅ "2024년 경기의 지역내총생산(명목)은 651,417,234백만원입니다."
✅ "2025년 3월 서울의 주택전세가격지수는 94.134 (2021.6=100)입니다."
✅ "2024년 서울의 자동차 등록대수는 3,176,933대입니다."
✅ "2024년 부산의 인구 천명당 범죄발생건수는 34.4건입니다."
✅ "2025년 11월 한국의 외래관광객수는 1,596,939명입니다."
✅ "2024년 한국의 교통사고 발생건수는 168,585건입니다."
✅ "2024년 서울의 의료기관 종사 의사수는 43,547명입니다."

📊 지원하는 통계 (83개 키워드)

인구/출산/사망

| 키워드 | 설명 | 주기 | |--------|------|------| | 인구, 총인구 | 총인구수 | 연 | | 출산율, 합계출산율 | 합계출산율 | 연 | | 출생아수, 출생아, 조출생률 | 출생 통계 | 연/분기/월 | | 사망자수, 사망자, 조사망률, 사망률 | 사망 통계 | 연/분기/월 | | 자연증가, 자연증가율 | 자연증감 | 연/분기/월 | | 기대수명, 기대여명, 평균수명 | 기대수명 | 연 |

혼인/이혼

| 키워드 | 설명 | 주기 | |--------|------|------| | 혼인율, 혼인건수, 조혼인율 | 혼인 통계 | 연/분기/월 | | 이혼율, 이혼건수, 조이혼율 | 이혼 통계 | 연/분기/월 |

고용/노동

| 키워드 | 설명 | 주기 | |--------|------|------| | 실업률 | 실업률 (시도별 지원) | 연 | | 고용률 | 고용률 (시도별 지원) | 연 | | 취업자수, 취업자 | 취업자 수 | 연 | | 실업자수, 실업자 | 실업자 수 | 연 | | 경제활동인구, 비경제활동인구 | 경제활동인구 | 연 | | 임금, 월평균임금, 월급, 평균임금 | 상용근로자 월평균 임금 (시도별) | 연 |

경제

| 키워드 | 설명 | 주기 | |--------|------|------| | GDP, 국내총생산 | GDP (국내총생산) | 연 | | GRDP, 지역내총생산 | 지역내총생산 (시도별) | 연 | | 경제성장률, 성장률, GDP성장률 | 경제성장률 | 연 | | 물가, 소비자물가, 소비자물가지수 | 소비자물가 (시도별) | 연/월 |

무역

| 키워드 | 설명 | 주기 | |--------|------|------| | 수출액, 수출 | 수출액 | 연 | | 수입액, 수입 | 수입액 | 연 | | 무역수지 | 무역수지 | 연 |

부동산

| 키워드 | 설명 | 주기 | |--------|------|------| | 주택가격, 주택매매가격, 주택가격지수 | 주택매매가격지수 (시도별) | 월 | | 아파트, 아파트가격, 아파트매매가격, 아파트가격지수 | 아파트매매가격지수 (시도별) | 월 | | 전세, 전세가격, 전세가격지수, 주택전세 | 주택전세가격지수 (시도별) | 월 | | 아파트전세, 아파트전세가격 | 아파트전세가격지수 (시도별) | 월 |

자동차/교통 🆕

| 키워드 | 설명 | 주기 | |--------|------|------| | 자동차, 자동차등록, 자동차대수 | 자동차 등록대수 (시도별) | 연 |

범죄/치안 🆕

| 키워드 | 설명 | 주기 | |--------|------|------| | 범죄, 범죄율, 범죄발생 | 인구 천명당 범죄발생건수 (시도별) | 연 |

관광

| 키워드 | 설명 | 주기 | |--------|------|------| | 관광객, 외래관광객, 입국자 | 외래관광객 입국자수 | 월 |

교통/안전 🆕

| 키워드 | 설명 | 주기 | |--------|------|------| | 교통사고, 교통사고발생, 사고건수 | 교통사고 발생건수 (시도별) | 연 |

의료/건강

| 키워드 | 설명 | 주기 | |--------|------|------| | 의사, 의사수, 의료인력 | 의료기관 종사 의사수 (시도별) | 연 |

대기환경 🆕

| 키워드 | 설명 | 주기 | |--------|------|------| | 미세먼지, PM2.5, 초미세먼지, 대기오염 | 초미세먼지(PM2.5) 농도 (시도별) | 월 | | PM10 | 미세먼지(PM10) 농도 (시도별) | 월 |

🗺️ 지역별 조회

17개 광역시도별 통계를 조회할 수 있습니다:

지원 지역: 전국, 서울, 부산, 대구, 인천, 광주, 대전, 울산, 세종, 경기, 강원, 충북, 충남, 전북, 전남, 경북, 경남, 제주

예시:

"서울 인구"
"부산 실업률"
"제주 출산율"
"경기도 고용률"
"서울 아파트가격"
"경기 GRDP"
"울산 임금"
"서울 전세가격"
"경기 자동차"
"부산 범죄율"
"서울 교통사고"           # 🆕 교통사고
"부산 의사수"             # 🆕 의료

📅 월별/분기별 조회 🆕

일부 통계는 월별 또는 분기별 조회가 가능합니다:

예시:

"2024년 10월 출생아수"    # 월별 조회
"2024년 3분기 사망자수"   # 분기별 조회
"2025년 1월 주택가격"     # 월별 조회

지원 통계: 출생아수, 사망자수, 혼인건수, 이혼건수, 자연증가, 물가, 주택가격, 아파트가격, 전세가격, 관광객

🛠️ 제공 도구 (8개)

핵심 도구 ⭐

| 도구 | 설명 | 예시 | |------|------|------| | quick_stats | 83개 키워드 빠른 조회 | "실업률", "GDP", "미세먼지", "교통사고", "의사수" | | quick_trend | 시계열 추세 분석 | "출산율 10년 추이" |

고급 도구

| 도구 | 설명 | |------|------| | search_statistics | KOSIS 통계표 키워드 검색 | | get_statistics_list | 주제별/기관별 통계 목록 탐색 | | get_statistics_data | 특정 통계표 데이터 조회 | | compare_statistics | 시점별/항목별 비교 분석 | | analyze_time_series | 상세 시계열 분석 | | get_recommended_statistics | 분야별 추천 통계 |

🔧 개발자 가이드

로컬 개발

# 개발 모드 (watch)
pnpm run dev

# MCP Inspector로 테스트
pnpm run inspector

# E2E 테스트
node e2e-test.js

프로젝트 구조

korea-stats-mcp/
├── src/
│   ├── index.ts              # 진입점 (stdio 트랜스포트)
│   ├── server.ts             # MCP 서버 설정
│   ├── tools/                # 8개 도구 구현
│   │   ├── quickStats.ts     # 빠른 조회
│   │   ├── quickTrend.ts     # 추세 분석
│   │   └── ...
│   ├── data/
│   │   └── quickStatsParams.ts  # 83개 키워드 매핑
│   └── api/
│       └── client.ts         # KOSIS API 클라이언트
├── api/
│   └── mcp.ts                # Vercel 서버리스 (원격 MCP)
└── tests/                    # Playwright 테스트

새 키워드 추가하기

src/data/quickStatsParams.ts에 새 키워드를 추가할 수 있습니다:

'새키워드': {
  orgId: '101',           // 기관 코드 (101 = 통계청)
  tableId: 'DT_XXXXX',    // 통계표 ID
  tableName: '통계표명',
  description: '설명',
  objL1: '00',            // 분류값 코드
  itemId: 'T10',          // 항목 코드
  unit: '단위',
}

📋 API 키

API 키가 내장되어 있어 별도 설정 없이 바로 사용 가능합니다.

💡 자체 API 키를 사용하려면 KOSIS OpenAPI에서 발급받아 src/config/index.ts의 apiKey 값을 변경하세요.

🤝 기여하기

기여를 환영합니다!

이 저장소를 Fork 합니다
새 브랜치를 생성합니다 (git checkout -b feature/새기능)
변경사항을 커밋합니다 (git commit -m 'feat: 새 기능 추가')
브랜치에 Push 합니다 (git push origin feature/새기능)
Pull Request를 생성합니다

기여 아이디어

[ ] 새로운 통계 키워드 추가
[ ] 영문 키워드 지원 (population, unemployment 등)
[ ] 지역명 풀네임 지원 (서울특별시 → 서울)
[ ] 더 많은 테스트 케이스

📄 라이선스

MIT License - 자유롭게 사용, 수정, 배포할 수 있습니다.

🔗 관련 링크

💬 문의

이슈나 질문이 있으시면 GitHub Issues에 등록해 주세요.

Made with ❤️ for Korean Statistics
_{KOSIS OpenAPI 기반 | MCP Compatible}