# OECD Stats MCP

**OECD 통계 사이트에 들어가지 않습니다.**
Claude에게 한국어로 물어보면 OECD 공식 수치가 출처와 함께 바로 나옵니다.

[![PyPI](https://img.shields.io/pypi/v/oecd-stats-mcp)](https://pypi.org/project/oecd-stats-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)

> OECD SDMX OpenAPI 기반 MCP 서버. Claude Desktop에서 바로 사용합니다.
> API 키가 필요 없고, 설정 파일에 네 줄만 추가하면 됩니다.

---

## 30초 만에 겪어보기

채팅창에 이렇게 칩니다.

```
나: OECD 회원국 중 우리나라 청년실업률 몇 위야?

Claude: 한국 청년실업률(15~24세) 6.41% — OECD 37개국 중 4위(낮은 순), 2025년

        • 상위: 일본 3.83% → 이스라엘 4.70% → 멕시코 5.86% → 한국 6.41%
        • OECD 평균 14.45% 대비 8.04%p 낮음, 백분위 91.7
        • 최하위: 스페인 24.84%, 스웨덴 24.28%

        ⚠ 주의: OECD 기준 청년은 15~24세, 국내 고용통계 청년은 15~29세라
          국내 발표 청년실업률과 직접 비교 불가.

        출처: OECD SDMX OECD.SDD.TPS,DSD_LFS@DF_IALFS_UNE_M,1.0
```

Data Explorer에 들어가 데이터셋을 찾고 → 차원 코드를 고르고 → 37개국을 정렬할
필요가 없습니다. **궁금한 것만 한국어로 던지면 됩니다.**

---

## 이럴 때 씁니다

### 📊 "우리나라 OECD에서 몇 위죠?" — 보고서에 늘 들어가는 그 한 줄

> **상황** — 정책보고서 현황 분석에 "OECD 대비 우리 수준"을 넣어야 합니다.
> 회원국 수치를 하나씩 받아 정렬하는 데 매번 30분.

```
나: 고용률 OECD 순위 알려줘
```

동일 시점 데이터만 골라 순위·백분위·평균 격차를 한 번에 냅니다.
**국가마다 최신 시점이 다르면 경고를 붙여** 사과와 배를 비교하는 일을 막습니다.

### 📈 "최근 10년 추세" — 챕터 하나가 한 줄로

> **상황** — 청년고용 대책 보고서에 시계열이 필요합니다.

```
나: 한국 청년실업률 2015년부터 추세 보여줘
```

변화율·연평균증가율(CAGR)·최고/최저 시점·추세 방향을 계산해서 돌려줍니다.
"등락 속 하락" 같은 판정까지 붙습니다.

### 🌍 "일본이랑 독일은 어때?" — 국가 비교표

```
나: 한국, 일본, 독일, 미국 고용률 비교해줘
```

여러 국가를 한 번에 조회해 정렬된 표로 만듭니다.

### 🔍 목록에 없는 통계도 — 검색해서 가져옵니다

```
나: OECD에 NEET 통계 있어? 있으면 한국 수치 알려줘
```

기본 지표에 없어도 OECD 전체 데이터셋을 검색하고, 구조를 확인해서 조회합니다.

---

## 🛡 이게 진짜 중요한 부분입니다

통계는 **틀린 값보다 맞는 값을 잘못 갖다 쓰는 것**이 사고가 됩니다.
OECD 고용률을 KOSIS 고용률인 줄 알고 보고서에 넣으면, 숫자는 정확한데 문장이 틀립니다.

그래서 이 서버는 **수치만 주지 않고 매번 해석 주의사항을 함께 보냅니다.**

| 지표 | 자동으로 붙는 경고 |
|------|-----------|
| **고용률** | 분모가 15~64세. KOSIS 고용률(15세 이상)과 값이 달라 같은 표에 넣으면 안 됨 |
| **청년실업률** | OECD 청년은 15~24세, 한국 고용통계는 15~29세 |
| **취업자수·실업자수** | **천 명 단위.** 명으로 인용하면 1000배 오류 (28,768 = 약 2,877만 명) |
| **평균임금** | 국민계정 기반 FTE 환산치. 사업체 임금조사(「고용형태별 근로실태조사」)와 성격이 다름 |

이 문구들은 지어낸 게 아니라 **OECD 메타데이터에서 확인한 것**입니다.
`UNIT_MULT=Thousands`, `PT_WAP_SUB`(생산가능인구 대비) 같은 원본 코드가 근거이고,
`python verify.py --meta`로 언제든 재확인할 수 있습니다.
OECD 원문에서 확인된 사실과 국내 통계 대조(작성자 판단)는 `[참고]`로 구분해 뒀습니다.

**무의미한 비교는 아예 막습니다.** `평균임금_원화`는 원화가 한국에만 제공되므로
국가 비교·순위 요청 자체를 거부하고 대안을 안내합니다.
"38개국 중 1위" 같은 답이 나올 여지를 없앴습니다.

**잠정치는 잠정치라고 말합니다.** 관측치 상태(`OBS_STATUS`)가 확정값이 아니면
응답에 명시합니다. 추정치를 실측처럼 인용하는 사고를 막습니다.

**모든 응답에 출처가 붙습니다.** dataflow ID가 함께 나오므로 그대로 각주에 쓰거나
직접 검증할 수 있습니다.

---

## 설치

**처음 설치하신다면 [INSTALL.md](./INSTALL.md)를 보세요.** 단계별로 쪼개고
자주 나는 실수와 오류별 조치까지 정리해 뒀습니다. 아래는 요약입니다.

### 1. uv 설치 (최초 1회, Python 불필요)

```powershell
winget install --id astral-sh.uv -e
```

macOS / Linux:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

설치 후 터미널을 새로 엽니다.

### 2. Claude Desktop 설정에 추가

설정 → 개발자 → 설정 편집 으로 `claude_desktop_config.json`을 열고
`mcpServers` 안에 아래를 넣습니다.

```json
{
  "mcpServers": {
    "oecd-stats": {
      "command": "uvx",
      "args": ["oecd-stats-mcp"]
    }
  }
}
```

### 3. Claude Desktop 완전 종료 후 재시작

창만 닫으면 백그라운드에 남습니다. **트레이 아이콘에서 종료**한 뒤 다시 실행하세요.

### 4. 확인

```
OECD 회원국 중 우리나라 청년실업률 몇 위야?
```

<details>
<summary><b>안 될 때 — 가장 흔한 두 가지</b></summary>

**`spawn uvx ENOENT`** — Claude Desktop이 앱 컨테이너로 실행돼 `uvx`를 못 찾는 경우입니다.
절대경로를 넣으면 해결됩니다.

```powershell
(Get-Command uvx).Source
```

```json
"command": "C:\\Users\\이름\\AppData\\Local\\Microsoft\\WinGet\\Links\\uvx.exe"
```

**설정 파일을 못 찾겠음** — Microsoft Store로 설치했다면 `%APPDATA%\Claude`가 없습니다.

```powershell
Get-ChildItem $env:APPDATA, $env:LOCALAPPDATA -Filter "claude_desktop_config.json" -Recurse -ErrorAction SilentlyContinue | Select-Object FullName
```

로그는 설정 파일과 같은 폴더의 `logs\mcp-server-oecd-stats.log`에 쌓입니다.

> JSON 실수 3종 — 역슬래시는 두 개(`\\`), 항목 사이엔 쉼표 필수, 마지막 항목 뒤엔 쉼표 금지.
> 문법이 깨지면 이 서버만이 아니라 **MCP가 통째로 안 뜹니다.**

</details>

---

## 무엇을 물어볼 수 있나

기본 제공 지표 9종입니다.

| 분야 | 지표 |
|------|------|
| 실업 | 실업률, 청년실업률, 실업률(월별), 실업자수 |
| 고용 | 고용률, 경제활동참가율, 취업자수 |
| 임금 | 평균임금(USD PPP), 평균임금(원화) |

정식 용어를 몰라도 됩니다. `연봉`→평균임금, `고용율`→고용률, `취업률`→고용률처럼
줄임말·오타를 자동으로 알아듣습니다. 국가명도 `한국`·`KOR`·`대한민국` 모두 인식합니다.

목록에 없는 통계는 이렇게 물어보면 됩니다.

```
나: OECD 통계로 뭘 물어볼 수 있어?
나: OECD에 노동시간 통계 있어?
```

검색 → 구조 확인 → 조회 3단계를 Claude가 알아서 밟습니다.

---

## 도구 8개

대부분의 질문은 앞의 다섯 개로 끝납니다. 나머지는 미등록 통계를 파고들 때 씁니다.

| 구분 | 도구 | 하는 일 |
|------|------|---------|
| **일상** | `oecd_list_indicators` | 등록 지표 목록 — 뭘 물어볼 수 있는지 |
| | `oecd_stats` | 단일 수치 (한 국가 × 한 지표) |
| | `oecd_trend` | 시계열 추세 — 변화율·CAGR·최고/최저·추세 판정 |
| | `oecd_compare` | N개국 비교표 + 시점 불일치 경고 |
| | `oecd_rank` | OECD 회원국 중 순위·백분위·평균 격차 |
| **확장** | `oecd_search_dataflow` | 미등록 통계 검색 (영문 키워드) |
| | `oecd_describe_flow` | 데이터셋의 차원·코드 + OECD 공식 정의문 |
| | `oecd_raw_query` | 임의 데이터셋 직접 조회 (탈출구) |

---

## ⚠ 알아둘 한계

**업무망(폐쇄망)에서는 동작하지 않습니다.** OECD 서버에 직접 접속하는 구조입니다.
폐쇄망에서 쓰려면 개인 PC에서 데이터를 뽑아 xlsx/csv로 반출한 뒤,
로컬 파일을 읽는 별도 도구를 쓰는 방식으로 가야 합니다.

**국내 통계와 정의가 다릅니다.** 위의 「해석 주의」 표를 반드시 확인하세요.
OECD는 국제 비교를 위해 조화(harmonised)된 정의를 쓰기 때문에,
KOSIS 수치와 다른 게 오류가 아니라 정상입니다.

---

## 개발자용

지표를 추가하거나 코드를 고칠 분만 해당됩니다.

```powershell
git clone https://github.com/seongapark/oecd_mcp.git
cd oecd_mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
```

> `activate`가 `PSSecurityException`으로 막히면 activate 없이
> `.venv\Scripts\python.exe`를 직접 쓰면 됩니다.
> 굳이 쓰려면 그 세션에서만 `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass`.
> `mcp` 1.x / 2.x 양쪽에서 동작합니다.

설정에는 `uvx` 대신 해당 python을 지정합니다.

```json
{
  "mcpServers": {
    "oecd-stats": {
      "command": "C:\\경로\\oecd_mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "oecd_mcp.server"],
      "cwd": "C:\\경로\\oecd_mcp"
    }
  }
}
```

### 지표가 제대로 나오는지 검증

```powershell
python verify.py                     # 9개 지표가 실제로 값을 받아오는지
python verify.py --meta              # 주의 문구의 근거를 OECD 메타데이터에서 확인
python verify.py --describe 고용률    # 해당 데이터셋의 차원·코드 전체
```

`[OK] 실업률 2025 = 2.79`처럼 찍히면 정상입니다.
`[EMPTY]`/`[FAIL]`이면 그 지표의 필터가 틀린 것이니 `--describe`로 실제 코드를 확인해
`oecd_mcp/indicators.py`의 `filters`를 고칩니다.
계열이 2건 이상 잡히면 **어느 차원이 안 걸렸는지 `[!]`로 짚어줍니다.**

> Windows 콘솔은 cp949라 한글이 깨질 수 있습니다. 파일로 받으세요.
> `python verify.py --meta 2>&1 | Out-File -Encoding UTF8 meta.txt` →
> `Get-Content meta.txt -Encoding UTF8`

### 지표 추가하는 법

1. `oecd_search_dataflow("NEET")` — 데이터셋 ID 확보
2. `oecd_describe_flow(agency, flow)` — 차원 ID와 코드 확인
3. `indicators.py`의 `INDICATORS`에 항목 추가, `ALIASES`에 한국어 별칭 추가
4. `note`에 해석 주의사항 작성 — **근거는 `--meta`로 확인한 OECD 원문에서**
5. `python verify.py`로 확인

### 코드 구조

```
oecd_mcp/
  client.py      SDMX REST 호출 + JSON 파싱 + 캐시 + 429 재시도
  indicators.py  지표 카탈로그 (데이터셋 + 필터 + 별칭 + 해석주의)
  countries.py   ISO3 ↔ 한국어 국가명
  analysis.py    추세·비교·순위 계산 (표준 라이브러리만)
  server.py      MCP 도구 정의
verify.py        지표 실동작 + 메타데이터 검증
```

<details>
<summary><b>설계 메모 — 차원 위치를 하드코딩하지 않은 이유</b></summary>

SDMX 조회 키는 `KOR..._T.Y_GE15..A`처럼 **점의 위치**로 차원을 지정합니다.
위치를 코드에 박아두면 OECD가 차원을 하나 추가하는 순간, 오류 없이 **조용히 엉뚱한 값**이
나옵니다. 통계 도구에서 가장 위험한 실패 방식입니다.

그래서 이 서버는 조회 전에 데이터 구조 정의(DSD)를 먼저 읽어 차원 순서를 얻고,
`{"REF_AREA":"KOR","SEX":"_T"}` 같은 **이름 기반 dict**로 키를 조립합니다
(`client.build_key`). 지정하지 않은 차원은 자동으로 전체가 됩니다.

부작용으로 필터가 덜 걸리면 여러 계열이 섞여 돌아오는데,
`server._series_note`가 이를 감지해 응답에 경고를 붙입니다.

**429 대응** — OECD는 짧은 시간에 요청이 몰리면 `429 Too Many Requests`를 줍니다.
`Retry-After` 헤더를 읽어 지수 백오프로 최대 4회 재시도하고, 연속 요청 사이에
최소 간격을 둡니다. 404 같은 영구 오류는 재시도하지 않습니다.
동일 질의는 6시간 캐싱됩니다.

</details>

---

## 라이선스

[MIT](./LICENSE)

## 참고

- [OECD SDMX-JSON API 문서](https://data.oecd.org/api/sdmx-json-documentation/)
- [OECD Data Explorer](https://data-explorer.oecd.org/) — 화면에서 데이터를 고른 뒤
  `Developer API` 버튼으로 쿼리를 복사할 수 있습니다
- [chrisryugj/korean-stats-mcp](https://github.com/chrisryugj/korean-stats-mcp) —
  KOSIS 기반 MCP. 이 프로젝트의 구조를 참고했습니다