한국은행 ECOS MCP 연동 — 기준금리·GDP 데이터를 Claude에서 조회
한국은행 ECOS API를 MCP로 연결해 Claude에서 기준금리·GDP·물가 경제통계를 바로 조회하는 방법을 단계별로 안내합니다. Korea Finance MCP 서버 설정 완전 가이드.
한국은행 ECOS API를 MCP로 연결하면 Claude에서 자연어로 “지금 기준금리가 얼마야?”, “올해 1분기 GDP 성장률 보여줘” 같은 질문을 던지는 즉시 실시간 경제통계 데이터를 받을 수 있습니다. 이 가이드는 Korea Finance MCP 서버를 이용해 ECOS API를 Claude Desktop에 연결하는 전 과정을 단계별로 설명합니다. ECOS API 키 발급부터 Claude에서 첫 조회까지 30분 안에 완료할 수 있습니다.
왜 ECOS를 MCP로 연결해야 하나요?
한국은행 ECOS(Economic Statistics System)는 기준금리, GDP, CPI, 환율, 통화량 등 국내 핵심 거시경제 데이터를 공식 제공하는 포털입니다. 직접 웹사이트에서 조회하면 통계 코드를 찾고, 기간을 설정하고, CSV를 내려받는 과정이 번거롭습니다.
MCP(Model Context Protocol)로 ECOS를 Claude에 연결하면 다음이 가능해집니다.
- 자연어 조회: “최근 3년간 기준금리 추이를 표로 보여줘”처럼 질문
- 즉각 분석: 데이터 수집과 AI 분석이 한 대화 안에서 완결
- 타 지표 교차 분석: DART 재무제표, KRX 주가 데이터와 함께 종합 분석
[Claude Desktop]
│ 자연어 질문
▼
[Korea Finance MCP 서버] ←→ ECOS API (한국은행)
│ ←→ DART API (금융감독원)
│ ←→ KRX API (한국거래소)
▼
[Claude] 분석·요약 응답준비물 체크리스트
| 항목 | 내용 | 필수 여부 |
|---|---|---|
| ECOS API 키 | ecos.bok.or.kr 무료 발급 | 필수 |
| Node.js 18 이상 | Korea Finance MCP 실행 환경 | 필수 |
| Git | 저장소 클론 | 필수 |
| Claude Desktop | MCP 클라이언트 | 필수 |
| DART API 키 | DART 재무제표 조회 시 추가 | 선택 |
단계별 연동 방법
1단계: ECOS API 키 발급
한국은행 ECOS 포털에서 무료로 API 인증키를 발급받습니다.
- https://ecos.bok.or.kr 에 접속해 회원가입
- 로그인 후 상단 메뉴 Open API → 인증키 신청 클릭
- 이용 목적 선택 후 신청 완료 → 즉시 키 발급
- 마이페이지 → Open API 인증키 관리에서 키 확인 및 복사
발급된 키는 영문·숫자 조합 40자리이며, 하루 10,000건까지 무료 호출이 가능합니다.
2단계: Korea Finance MCP 저장소 클론
Korea Finance MCP는 ECOS·DART·KRX 등 한국 주요 금융 API를 통합한 MCP 서버입니다. GitHub에서 직접 클론합니다.
git clone https://github.com/emceeKim/korea-finance-mcp.git
cd korea-finance-mcp3단계: 의존성 설치 및 환경변수 설정
npm install프로젝트 루트에 .env 파일을 생성하고 발급받은 API 키를 입력합니다.
# .env 파일 예시
ECOS_API_KEY=여기에_발급받은_ECOS_API_키_입력
# DART API 키도 사용한다면 아래 추가
# DART_API_KEY=여기에_DART_API_키_입력.env 파일은 절대로 Git에 커밋하지 않도록 .gitignore에 포함되어 있는지 반드시 확인하세요.
4단계: MCP 서버 실행 및 확인
Korea Finance MCP는 HTTP-SSE(Server-Sent Events) 방식으로 동작합니다.
npm start터미널에 서버 주소(예: http://localhost:3000)가 출력되면 정상 실행된 것입니다. 브라우저 또는 curl로 엔드포인트를 호출해 응답을 확인합니다.
curl http://localhost:3000/health5단계: Claude Desktop에 MCP 서버 등록
Claude Desktop 설정 파일을 열어 Korea Finance MCP를 추가합니다.
macOS 설정 파일 경로
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 설정 파일 경로
%APPDATA%\Claude\claude_desktop_config.json설정 파일에 다음 내용을 추가합니다. 기존 mcpServers 항목이 있으면 그 안에 추가하고, 없으면 아래와 같이 전체 구조로 작성합니다.
{
"mcpServers": {
"korea-finance": {
"url": "http://localhost:3000/sse",
"transport": "http-sse"
}
}
}저장 후 Claude Desktop을 완전히 종료하고 다시 실행합니다.
6단계: ECOS 데이터 조회 테스트
Claude Desktop 재시작 후 새 대화를 열어 다음과 같이 질문해 보세요.
- “현재 한국은행 기준금리를 알려줘”
- “2024년 연간 GDP 성장률은 얼마야?”
- “최근 12개월 소비자물가지수 추이를 표로 보여줘”
- “원/달러 환율 최근 1개월 데이터 조회해줘”
ECOS에서 데이터를 가져와 Claude가 자연어로 요약·분석해 응답하면 연동 성공입니다.
조회 가능한 주요 경제지표
Korea Finance MCP가 ECOS를 통해 지원하는 대표 지표들입니다.
| 지표 분류 | 주요 항목 | 조회 예시 질문 |
|---|---|---|
| 금리 | 기준금리, 콜금리, 국고채 수익률 | ”기준금리 2024년 변동 내역” |
| 국민계정 | GDP, GNI, 경제성장률 | ”작년 분기별 GDP 성장률” |
| 물가 | CPI, PPI, GDP 디플레이터 | ”올해 소비자물가 상승률” |
| 환율 | 원/달러, 원/유로, 원/엔 | ”원달러 환율 연간 평균” |
| 통화량 | M1, M2, 광의유동성 | ”M2 통화량 최근 추이” |
| 국제수지 | 경상수지, 자본수지 | ”2024년 경상수지 흑자 규모” |
흔한 오류와 해결 방법
”API 키가 유효하지 않습니다” 오류
ECOS API 키를 .env 파일에 정확히 입력했는지 확인합니다. 키 앞뒤에 공백이 포함되면 인증 실패가 발생합니다. 키 발급 후 24시간 이내에 활성화되므로, 방금 발급했다면 잠시 기다렸다 재시도하세요.
Claude Desktop에서 MCP 서버가 보이지 않는 경우
설정 파일 JSON 문법 오류가 가장 흔한 원인입니다. 쉼표 누락, 따옴표 불일치를 점검하세요. JSON 유효성 검사기를 활용하면 빠르게 확인할 수 있습니다. 또한 Korea Finance MCP 서버가 실행 중인 상태인지, 포트 번호가 설정 파일과 일치하는지 확인합니다.
데이터 조회 결과가 없는 경우
ECOS API는 통계 코드와 기간 형식에 민감합니다. Claude에게 구체적인 기간을 명시해 질문하면 더 정확한 데이터를 얻을 수 있습니다. 예: “2024년 1월부터 12월까지 월별 기준금리 데이터”.
HTTP-SSE 연결 끊김
장시간 사용 시 SSE 연결이 끊길 수 있습니다. Claude Desktop을 재시작하거나, 서버를 재실행하면 대부분 해결됩니다. 지속적인 운영이 필요하다면 pm2 같은 프로세스 매니저로 서버를 관리하는 것을 권장합니다.
관련 금융 MCP 서버
ECOS 외에도 한국 금융 데이터를 AI로 분석하는 데 유용한 MCP 서버들을 함께 사용하면 더욱 풍부한 분석이 가능합니다.
- Korea Finance MCP: ECOS·DART·KRX·국토부 실거래가를 하나의 서버로 통합
- Korea Stock MCP: DART·KRX로 한국 주식 분석 특화
- DART MCP 서버: 상장기업 전자공시 재무제표 분석
금융 카테고리 전체 MCP 서버 목록에서 더 많은 한국 금융 데이터 MCP를 확인하세요.
자주 묻는 질문
ECOS API 키는 유료인가요?
아니요, 한국은행 ECOS Open API 키는 무료로 발급됩니다. ecos.bok.or.kr에서 회원가입 후 Open API 신청 메뉴를 이용하면 됩니다.
Korea Finance MCP는 npx로 바로 설치할 수 있나요?
현재 Korea Finance MCP는 npm 패키지로 배포되지 않고 HTTP-SSE 방식으로 동작합니다. GitHub 저장소를 직접 클론해 로컬에서 서버를 실행한 뒤 Claude Desktop에 등록하는 방식으로 사용합니다.
ECOS에서 어떤 경제 지표를 조회할 수 있나요?
기준금리, GDP 성장률, 소비자물가지수(CPI), 생산자물가지수(PPI), 환율, 통화량(M1/M2), 경상수지 등 한국은행이 공표하는 수백 개의 경제통계 시계열 데이터를 조회할 수 있습니다.
Korea Finance MCP는 ECOS 외에 어떤 API를 지원하나요?
DART OpenDART(전자공시), KRX(한국거래소), 국토부 RTMS(실거래가), 한국부동산원 R-ONE, data.go.kr 등 한국 주요 금융·부동산 공공 데이터를 통합 지원합니다.
Claude Code와 Cursor에서도 사용할 수 있나요?
네, MCP를 지원하는 모든 클라이언트에서 동일하게 사용할 수 있습니다. Claude Code는 프로젝트 설정 파일, Cursor는 MCP 설정에서 서버 주소를 등록하면 됩니다.
API 키를 여러 개 등록해야 하나요?
Korea Finance MCP는 ECOS, DART, KRX 등 여러 API를 통합하므로, 사용하려는 데이터 소스에 따라 해당 서비스의 API 키를 각각 발급받아 .env 파일에 설정해야 합니다. ECOS만 사용한다면 ECOS API 키 하나로 충분합니다.
다음 단계
Korea Finance MCP로 ECOS 연동에 성공했다면, 이제 더 풍부한 금융 데이터 분석에 도전해 보세요. DART 전자공시 데이터를 추가하면 “삼성전자의 최근 분기 실적을 기준금리 변화와 함께 분석해줘”처럼 매크로·개별 기업 데이터를 교차 분석할 수 있습니다.
더 많은 한국 금융 MCP 서버를 탐색하려면 MCP 서버 전체 목록을 방문하거나, 금융 카테고리 페이지에서 엄선된 서버들을 확인해 보세요. 유용한 MCP 서버를 발견하셨다면 MCP모아 가이드 목록에서 관련 가이드도 함께 참고하세요.