# KOSIS MCP

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

[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
[![KOSIS](https://img.shields.io/badge/KOSIS-OpenAPI-green)](https://kosis.kr/openapi/)

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

---

## 30초 만에 겪어보기

> 채팅창에 이렇게 칩니다 (Claude.ai 커넥터 등록 후 — [아래 설치법](#설치-3가지-방법) 참고)

```
나: 광진구 고용률 알려줘

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

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

---

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

국가데이터처 통계는 [KOSIS](https://kosis.kr)에 다 있습니다. 문제는 **꺼내 쓰는 비용**입니다.
통계표 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개 + 자연어 별칭 88개

| 분야 | 예시 키워드 |
|------|------------|
| 인구·출산·고령 | 인구, 출산율, 출생아수, 사망률, 기대수명, 고령인구, 노령화지수 |
| 혼인·이혼 | 혼인건수, 이혼율, 초혼연령, 평균초혼연령 |
| 고용·소득 | 실업률, 고용률, 취업자수, 경제활동인구, 월평균임금 |
| 경제 | GDP, 경제성장률, 물가(소비자물가지수), GRDP(지역내총생산) |
| 무역 | 수출, 수입, 무역수지 |
| 주거 | 주택매매가격, 아파트가격, 전세가격 |
| 환경·교통·사회 | 미세먼지(PM2.5/PM10), 자동차등록, 교통사고, 범죄율, 의사수, 외래관광객 |

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

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

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

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

---

## 14개 도구

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

| 구분 | 도구 | 하는 일 |
|------|------|---------|
| **자연어 즉답** ⭐ | `quick_stats` | 자연어 한 줄 → KOSIS 수치 즉답 |
| | `quick_trend` | 시계열 추세 + 변화율 + 최고/최저점 (자연어 기간 인식) |
| | `quick_rank` 🆕 | "우리 지역 전국 몇 위?" — 17개 시도 또는 시군구 전수 대비 순위·백분위·평균 격차·순위 변동. 동일 표·동일 시점 단일 조회로 비교가능성 보장 |
| **출처·각주** 🆕 | `explain_statistic` | 통계 공식 정의·작성목적·조사주기·용어해설 + 보고서 인용 각주 문구 생성 |
| **체인** ⛓ | `chain_region_brief` | 한 지역 13개 지표 종합 브리핑 (연설용 한 줄 모드 포함) |
| | `chain_compare_regions` | N개 지역 × M개 지표 매트릭스 + 순위 (최대 17×8) |
| | `chain_policy_indicator` | 7개 정책 영역 묶음 10년 시계열 |
| **검색·탐색** | `search_statistics` | KOSIS 통계표 키워드 검색 |
| | `get_statistics_list` | 주제별·기관별 트리 탐색 + 분야별 추천 |
| | `get_table_info` | 통계표 메타데이터(분류·항목·주기) |
| **정밀 데이터** | `get_statistics_data` | 특정 통계표 데이터 조회 (지역명·항목명 자동 매칭) |
| | `compare_statistics` | 시점별·항목별 정밀 비교 |
| | `analyze_time_series` | 상세 시계열 (CAGR·표준편차·추세선) |
| **파일 통계표** | `fetch_kosis_excel` | KOSIS 파일통계표(`.xlsx`) 다운로드·파싱 — 자치구 통계연보 등 OpenAPI 미지원 표 커버 |

---

## 설치

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

**준비물**: Python 3.11+ · [KOSIS OpenAPI 키](https://kosis.kr/openapi/) (무료)

```bash
git clone https://github.com/chrisryugj/kosis-mcp.git
cd kosis-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
```

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

원클릭 등록:

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

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

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

```bash
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)

```bash
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](https://vercel.com/marketplace/upstash) 연동 후 `REDIS_URL` 설정 (미설정 시 인메모리 캐시)
- Cursor 연결:

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

로컬에서 HTTP만 띄울 때:

```bash
KOSIS_API_KEY=... kosis-mcp --http --port 3000
```

---

## 정확성과 신뢰

- **공식 출처** — 모든 수치는 국가데이터처 KOSIS OpenAPI를 실시간 조회합니다. 응답에 통계표 ID가 표기되어 그대로 인용·검증할 수 있습니다.
- **추계 데이터 구분** — 장래추계가 포함된 통계는 "추계" 안내가 자동으로 붙습니다.
- **자치구 데이터 무결성** — 자치구 단위 데이터가 KOSIS에 없으면 임의로 광역시도 값을 자치구 값인 척 답하지 않고, "광역시도 데이터로 대체했다"고 명시합니다.
- **캐시** — 동일 질의는 6시간 캐싱하여 빠르게 응답하되, 통계 갱신 주기를 해치지 않습니다.

---

## 변경 이력

<details>
<summary>v1.8 — 프로덕션 정확성 하드닝 + quick_rank·explain_statistic + 통합 호스트 이전</summary>

- **잘못된 수치가 정답처럼 나가던 경로 차단** — 인식 못 한 지역명에 전국값을 조용히 반환하던 동작 제거(에러 + 지원 지역 안내로 교체), `청년실업률`·`연봉`처럼 **정의가 다른 지표로의 무단 별칭 치환 제거**(안내 문구로 전환), `다문화인구`·`유소년인구` 같은 복합어가 `인구`에 부분매칭되던 버그 차단
- **노령화지수 라우팅 교체** — 장래추계 전용 표(`DT_1YL12501E`, 2033~2052년)에서 인구총조사 실측(`DT_1IN2030`)으로. 고령인구비율은 별도 키워드로 분리(지수 ≠ 비율)
- 인구동향(출생·사망·혼인·이혼) 최근 시점에 **잠정치 안내** 자동 부착, 출처 표기에 통계표 ID + 최종갱신일(`LST_CHN_DE`) 포함
- **신규 도구 2종** — `quick_rank`(동급 지자체 전수 대비 순위·백분위·평균 격차·순위 변동), `explain_statistic`(통계 정의·작성목적·조사주기 + 보고서 인용 각주). **도구 12개 → 14개**
- 견고성 — 동일 키 in-flight 요청 병합(캐시 stampede 방지), 체인 도구 동시성 캡 8(17×8=136 동시 KOSIS 호출 방지), vitest 단위 테스트 도입
- v1.8.1 — 통계설명을 정식 엔드포인트(`statisticsExplData.do`)로 교체 + 자치구 코드 lookup 검증 강화
- v1.8.2 ~ v1.8.5 — MCP 도구 annotations(read-only·비파괴·멱등·openWorld) 부여, 도구명을 영문 그대로 노출(비-ASCII title이 붙으면 claude.ai 웹이 도구 목록을 인식하지 못함), 과대했던 도구 description 축소
- **배포를 통합 호스트로 이전** — 공식 주소 `mcp.gomdori.app/stats` (구 `kosis-mcp.fly.dev` 중단)

</details>

<details>
<summary>v2.0 — Python FastMCP 전면 교체</summary>

- TypeScript/Node MCP → **Python FastMCP 3.4.7** 전면 포팅
- npm / gomdori 통합 호스트 의존 제거 — 독립 stdio + Streamable HTTP
- 엑셀 파싱: kordoc → **openpyxl** 마크다운 변환
- 14개 도구·2개 리소스·1개 프롬프트 유지

</details>

---

## 라이선스

MIT

---

## 참고한 프로젝트

- **[Dayoooun/kosis-mcp](https://github.com/Dayoooun/kosis-mcp)** — 이 프로젝트의 포크 시작점. 원본에 깊은 감사를 표합니다. 라이선스는 원본과 동일한 MIT.
- **[FastMCP](https://gofastmcp.com)** — Python MCP 서버 프레임워크.