korea-bok-stats-mcp
한국은행 경제통계시스템(ECOS) Open API를 Claude에서 바로 조회할 수 있게 해주는 MCP 서버입니다.
제공하는 도구 (Tools)
| 도구 | 설명 |
|---|---|
search_statistic_tables |
통계표 목록 검색/조회 (예: "본원통화 구성내역" 통계표 코드 찾기) |
get_statistic_data |
★ 실제 시계열 수치 데이터 조회 (예: 2015~2021년 GDP 값) |
get_statistic_items |
특정 통계표의 세부 항목코드 목록 조회 |
get_key_statistics |
100대 주요 통계지표 요약 조회 (경제성장률, 기준금리 등) |
get_statistic_meta |
통계 메타데이터(작성기준, 연혁 등) 조회 |
search_statistic_word |
경제/통계 용어 설명 조회 (803개 용어) |
⚠️ 실측으로 확인된 제약사항이나 명세서와 다른 실제 동작은 아래 "알려진 제약사항" 절을 참고하세요.
일반적인 사용 흐름
search_statistic_tables로 원하는 통계의 통계표코드를 찾는다- (필요시)
get_statistic_items로 해당 통계표의 항목코드를 확인한다 get_statistic_data로 실제 수치를 조회한다
간단한 지표는 get_key_statistics(100대 통계지표)만으로 충분할 수 있습니다.
환경 변수
| 변수명 | 설명 |
|---|---|
BOK_API_KEY |
한국은행 ECOS에서 발급받은 Open API 인증키 |
인증키는 ECOS Open API 서비스에서 회원가입 후 신청하면보통 1일 이내 발급됩니다.
설치 및 로컬 실행
pip install -r requirements.txt
cp .env.example .env # BOK_API_KEY 값을 채워넣기
python server.py
배포 (Fly.io)
fly launch --no-deploy
fly secrets set BOK_API_KEY=발급받은키
flyctl deploy
Claude.ai 커넥터 연결
배포 완료 후 나온 주소 뒤에 반드시 /mcp를 붙여서 연결합니다.
https://<앱이름>.fly.dev/mcp
연결 후에는 새 대화창을 열어서 도구 목록이 정상적으로 뜨는지 확인하세요.(기존에 열려 있던 대화창에는 새 커넥터가 자동 반영되지 않을 수 있습니다.)
이용 제한 (Rate Limit)
이 서버는 API 키 인증 없이 공개되어 있어 아래 제한이 적용됩니다:
- 1분당 3회 초과 호출 시 일시 차단
- 1시간 내 5회 이상 제한 초과 시 24시간 차단
- 하루 총 30회 초과 호출 시 제한
정상적인 대화 중 필요한 만큼만 도구를 호출하는 경우에는 문제가 되지 않습니다.
⚠️ 차단되어도 HTTP 상태 코드는 200 OK로 옵니다. 이 서버는 MCP(JSON-RPC over HTTP)프로토콜을 쓰기 때문에, rate limit에 걸린 요청도 HTTP 레벨에서는 정상 응답(200)이고,대신 JSON-RPC 응답 바디 안에
"isError": true와"Rate limit exceeded..."메시지가담겨 옵니다. 따라서curl등으로 직접 테스트할 때 HTTP 상태 코드만 보고 "차단이 안 된다"고판단하면 안 되고, 반드시 응답 바디의isError/content[].text를 확인해야 합니다(2026-08-17 배포 환경 실측으로 확인).
라이선스 / 출처
본 서비스는 한국은행 ECOS Open API가 제공하는 공개 데이터를 활용합니다.데이터 저작권 및 이용 조건은 한국은행 경제통계 OPEN API 이용약관을따릅니다.
알려진 제약사항
2026-08-17 실제 키로 6개 API 전부 호출하여 확인한 내용입니다.
- StatisticSearch 선택 파라미터(통계항목코드1~4): 세그먼트를 완전히 생략(예:
.../722Y001/M/202301/202312)해도, 통계항목코드1만 채우고 2~4를 생략해도, 명세서 샘플처럼?를 리터럴로 채워도(.../0101000/?/?/?) 모두 동일하게 정상 동작함을 확인했습니다.즉 "부분 채움 금지" 같은 제약은 없습니다. - StatisticTableList의 통계표코드(선택): 생략 시 세그먼트를 완전히 제거하면 정상동작합니다 (빈 세그먼트를 남길 필요 없음).
- 한글 경로 세그먼트 URL 인코딩 (StatisticMeta의 데이터명, StatisticWord의 용어):httpx가 한글 문자열을 그대로 전달해도 자동으로 UTF-8 URL 인코딩을 처리합니다. 별도로
urllib.parse.quote를 적용한 결과와 동일했으므로, 이 서버는 한글을 그대로 전달합니다. - JSON 응답 최상위 구조: 정상 응답은
{"<서비스명>": {"list_total_count": N, "row": [...]}}형태이고, 에러/데이터없음 응답은{"RESULT": {"CODE": "...", "MESSAGE": "..."}}형태입니다.CODE가INFO-200(데이터 없음)인 경우는 에러로 취급하지 않고 빈 결과(list_total_count: 0)로변환해서 반환합니다. 그 외 코드는 에러로 처리되어 도구 응답에{"error": "[코드] 메시지"}형태로 담깁니다. - 응답 인코딩: HTTP 헤더는
charset=UTF-8로 표기되며 실제로도 유효한 UTF-8 바이트입니다.(일부 터미널에서 콘솔 출력 시 한글이 깨져 보일 수 있으나, 이는 콘솔 코드페이지 문제일 뿐응답 데이터 자체는 정상입니다.) - Rate limit 클라이언트 IP 추출: fly.io 배포 환경에서는
Fly-Client-IP헤더(가장 신뢰할수 있는 실제 클라이언트 IP)를 우선 사용하고, 없으면X-Forwarded-For의 첫 번째 값을사용합니다. 배포 환경 실측(2026-08-17)으로Fly-Client-IP가 정상적으로 들어오고IP별로 카운터가 올바르게 분리됨을 확인했습니다. - Rate limit 차단 시 HTTP 상태 코드: 위 "이용 제한" 절 참고 — 차단되어도 HTTP 200이오며, 차단 여부는 JSON-RPC 응답 바디의
isError필드로 판단해야 합니다.
