ecos-mcp-server

한국은행 ECOS(경제통계시스템) Open API를 위한 MCP(Model Context Protocol) 서버. /mnt/skills/user/bok-ecos/SKILL.md의 원칙(추측 금지, ECOS 원자료만 사용, 오류 시 다른 출처로 대체 금지)을 도구 설명(description)에 그대로 내장해두었습니다 — Claude가 이 서버의 툴을 쓸 때 같은 규칙을 자연히 따르게 됩니다.

제공 도구 (5개)

도구	대응 ECOS 서비스	용도
ecos_search_series	StatisticSearch	실제 시계열 데이터 조회
ecos_list_tables	StatisticTableList	통계표 코드 탐색
ecos_list_items	StatisticItemList	특정 통계표의 항목코드/주기/단위 확인
ecos_key_statistics	KeyStatisticList	100대 핵심지표
ecos_search_word	StatisticWord	통계 용어 설명

모든 도구는 ECOS가 실제로 반환한 JSON을 그대로(raw) 포함해서 돌려주고, 실패 시에도 ok: false와 함께 ECOS의 실제 오류 코드/메시지를 그대로 전달합니다 — 서버가 임의로 값을 만들어내지 않습니다.

---

방법 1 — 로컬 사용 (Claude Code / Claude Desktop)

가장 빠르게 시작하는 방법입니다. 컴퓨터의 인터넷 연결을 그대로 쓰므로 별도 배포 없이 바로 동작합니다.

1) 설치

cd ecos-mcp-server
npm install
cp .env.example .env
# .env 파일을 열어 ECOS_API_KEY=발급받은키  로 채워넣기

2) 단독 실행 테스트 (선택)

npm run start:stdio

stdio transport ready 로그가 뜨면 정상입니다. Ctrl+C로 종료하세요.

3) Claude Code에 등록

Claude Code 프로젝트 루트(또는 전역 설정)의 .mcp.json에 추가:

{
  "mcpServers": {
    "bok-ecos": {
      "command": "node",
      "args": ["/절대/경로/ecos-mcp-server/src/stdio.js"],
      "env": {
        "ECOS_API_KEY": "발급받은키"
      }
    }
  }
}

또는 터미널에서 바로 등록:

claude mcp add bok-ecos -- node /절대/경로/ecos-mcp-server/src/stdio.js

4) Claude Desktop에 등록 (Code 탭 포함)

claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)에 동일한 형식으로 추가 후 Claude Desktop 재시작.

등록 후에는 채팅에서 바로 이렇게 요청하면 됩니다:

"ecos_list_tables로 '잠재' 관련 통계표를 찾아줘" "ecos_search_series로 722Y001(기준금리) 최근 10년치를 연도별로 조회해줘"

---

방법 2 — 원격 배포 (claude.ai 웹/모바일 커넥터)

claude.ai 채팅창(이 환경)에서 직접 쓰려면, 공인 URL로 접근 가능한 서버가 필요합니다. 아래는 Render.com 무료/저가 플랜 기준 예시입니다 (Railway, Fly.io 등도 동일한 방식).

1) GitHub에 푸시

cd ecos-mcp-server
git init
git add .
git commit -m "ecos mcp server"
git remote add origin <본인의 github 저장소 URL>
git push -u origin main

2) Render.com에서 배포

1. https://render.com → New → Web Service → 방금 만든 저장소 선택
2. Build Command: npm install
3. Start Command: npm start
4. Environment → ECOS_API_KEY = 발급받은 개인 키 추가
5. 배포 완료 후 발급되는 URL 확인 (예: https://ecos-mcp-server.onrender.com)

3) claude.ai에 커넥터로 등록

1. claude.ai → 설정(Settings) → Connectors → "Add custom connector"
2. URL에 https://ecos-mcp-server.onrender.com/mcp 입력 (경로 끝에 /mcp 필수)
3. 저장 후 새 대화에서 도구 목록에 bok-ecos가 나타나는지 확인

이후로는 claude.ai 채팅에서 "기준금리 최근 조회해줘"처럼 자연어로 요청하면 Claude가 해당 도구를 호출해 실제 ECOS 응답을 기반으로 답합니다.

무료 플랜은 일정 시간 미사용 시 서버가 슬립 상태가 되어 첫 호출이 느릴 수 있습니다. 자주 쓰신다면 유료 플랜이나 상시 구동 인스턴스를 권장합니다.

---

개인 키 vs 공개(sample) 키

• ECOS_API_KEY를 설정하지 않으면 공개 sample 키로 동작하며, ECOS 정책상 1회 호출당 최대 10행으로 제한됩니다.
• 개인 키(예: 기존에 쓰시던 M8JW6WYR9SUATYN29MGE)를 넣으면 더 큰 범위를 한 번에 조회할 수 있습니다. 정확한 최대 행 수는 ECOS 공식 문서/마이페이지에서 확인하시는 것이 가장 정확합니다 (이 서버가 임의로 단정하지 않습니다).

안전 설계 원칙

• 코드에 API 키를 하드코딩하지 않고 환경변수로만 주입합니다.
• ECOS가 HTTP 200이면서 내부적으로 오류(INFO-200, ERROR-301, ERROR-602 등)를 반환하는 경우를 감지해 그대로 ok:false로 전달합니다 — 다른 출처로 대체하지 않습니다.
• 모든 응답에 실제 요청 URL(키는 ***로 마스킹)을 포함해 검증 가능성을 남깁니다.