OECD Stats MCP

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

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개국을 정렬할 필요가 없습니다. 궁금한 것만 한국어로 던지면 됩니다.

Related MCP server: korean-stat-mcp

이럴 때 씁니다

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

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

나: 고용률 OECD 순위 알려줘

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

설치

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

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

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

macOS / Linux:

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

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

2. Claude Desktop 설정에 추가

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

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

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

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

4. 확인

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

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

(Get-Command uvx).Source

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

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

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가 통째로 안 뜹니다.

무엇을 물어볼 수 있나

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

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

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

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

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

도구 8개

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

⚠ 알아둘 한계

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

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

개발자용

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

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을 지정합니다.

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

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

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        지표 실동작 + 메타데이터 검증

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시간 캐싱됩니다.

라이선스

MIT

참고

• OECD SDMX-JSON API 문서

• OECD Data Explorer — 화면에서 데이터를 고른 뒤 Developer API 버튼으로 쿼리를 복사할 수 있습니다

• chrisryugj/korean-stats-mcp — KOSIS 기반 MCP. 이 프로젝트의 구조를 참고했습니다