ECOS API 경제통계 MCP 연동 — GDP·물가·금리를 AI로 분석하기

Q: Claude Desktop과 Claude Code 중 어디에서 설정하나요?

두 환경 모두 MCP를 지원합니다. Claude Desktop은 claude_desktop_config.json을 수정해 연결하고, Claude Code는 프로젝트 루트의 .mcp.json 파일 또는 Claude Code CLI 설정으로 추가합니다. 경제 데이터 개인 분석이라면 Claude Desktop이 더 간편합니다.

ECOS API 경제통계를 MCP로 연결하면 Claude에서 “올해 3분기 GDP 성장률 얼마야?”, “최근 2년간 소비자물가 추이 표로 보여줘”처럼 자연어 한 문장으로 한국은행 공식 통계를 즉시 받아볼 수 있습니다. 이 가이드는 ECOS StatisticSearch API를 MCP 서버로 감싸 Claude Desktop에 등록하는 과정을 단계별로 안내합니다. API 키 발급부터 GDP·물가·금리 데이터 첫 조회까지 30분 내에 완료할 수 있습니다.

ECOS 경제통계 MCP가 필요한 이유

한국은행 경제통계시스템(ECOS)은 GDP·물가·금리·환율·통화량 등 국내 핵심 거시경제 지표를 공식 제공하는 포털입니다. 직접 웹사이트에서 내려받으면 통계표 코드를 찾고, 기간을 설정하고, CSV를 열어 가공하는 과정이 매번 반복됩니다.

MCP(Model Context Protocol)는 AI 어시스턴트가 외부 데이터 소스를 표준화된 방식으로 직접 호출하도록 해주는 규격입니다. ECOS를 MCP로 연결하면 다음과 같은 작업이 대화 한 번으로 끝납니다.

자연어 조회: “2023년 분기별 GDP 성장률을 표로 정리해줘”
즉각 분석: 데이터 수집과 AI 해석이 같은 대화에서 완결
리포트 자동화: “기준금리 인상 시점과 물가 상승률 변화를 함께 분석한 보고서를 마크다운으로 작성해줘”

데이터 흐름 구조

사용자 자연어 질문
        │
        ▼
Claude Desktop (MCP 클라이언트)
        │  MCP 프로토콜 (JSON-RPC over stdio)
        ▼
ECOS 경제통계 MCP 서버 (로컬 Node.js 프로세스)
        │  HTTPS REST
        ▼
한국은행 ECOS Open API
        │  JSON 응답 (통계 시계열 데이터)
        ▼
Claude — 분석·요약·시각화 텍스트로 답변

준비물

항목	설명	비고
ECOS API 키	한국은행 ecos.bok.or.kr 무료 발급	하루 1만 건 무료
Node.js 18 이상	MCP 서버 실행 환경	`node -v`로 확인
Claude Desktop	MCP 클라이언트 앱	Anthropic 공식 앱
터미널	명령 실행	macOS Terminal, Windows PowerShell
텍스트 편집기	코드·설정 파일 작성	VS Code 등

단계별 설정 방법

1단계: ECOS API 키 발급

한국은행 ECOS 포털에서 무료 API 인증키를 발급받습니다.

https://ecos.bok.or.kr 에 접속 후 회원가입
로그인 후 상단 메뉴에서 Open API → 인증키 신청 클릭
이용 목적(개인 연구·학습 등)을 입력하고 신청 완료
마이페이지 → Open API 인증키 관리에서 발급된 키 확인 및 복사

발급된 키는 영문·숫자 조합으로, 통상 신청 즉시 활성화됩니다. 하루 10,000건까지 무료 호출이 가능하며 개인 분석 용도라면 거의 초과하지 않습니다.

2단계: Node.js 환경 및 MCP SDK 설치

터미널에서 작업 디렉터리를 생성하고 필요한 패키지를 설치합니다.

mkdir ecos-stats-mcp && cd ecos-stats-mcp
npm init -y
npm install @modelcontextprotocol/sdk

Node.js 18 이상이 설치되어 있어야 합니다. node -v로 버전을 확인하세요.

3단계: ECOS 경제통계 MCP 서버 코드 작성

아래 코드로 index.js 파일을 작성합니다. ECOS의 StatisticSearch API를 사용해 GDP·물가·금리 세 가지 지표를 조회하는 도구를 제공합니다.

주요 ECOS 통계표 코드

지표	통계표 코드	주기	단위
실질 GDP 성장률	111Y002	분기	%
소비자물가지수(CPI)	021Y002	월	지수
한국은행 기준금리	722Y001	일	%
콜금리(익일물)	817Y002	일	%
원달러 환율	731Y001	일	원

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const ECOS_API_KEY = process.env.ECOS_API_KEY;
const ECOS_BASE = "https://ecos.bok.or.kr/api/StatisticSearch";

// ECOS API 호출 헬퍼
async function fetchEcos(statCode, freq, startDate, endDate, itemCode = "") {
  const url = [
    ECOS_BASE,
    ECOS_API_KEY,
    "json",
    "kr",
    "1",
    "100",
    statCode,
    freq,
    startDate,
    endDate,
    itemCode,
  ]
    .filter(Boolean)
    .join("/");

  const res = await fetch(url);
  const data = await res.json();
  return data?.StatisticSearch?.row ?? [];
}

const server = new Server(
  { name: "ecos-stats-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_gdp_growth",
      description:
        "한국은행 ECOS에서 실질 GDP 성장률(분기) 데이터를 조회합니다.",
      inputSchema: {
        type: "object",
        properties: {
          startDate: {
            type: "string",
            description: "시작 분기 (YYYYQ 형식, 예: 2022Q1)",
          },
          endDate: {
            type: "string",
            description: "종료 분기 (YYYYQ 형식, 예: 2024Q3)",
          },
        },
        required: ["startDate", "endDate"],
      },
    },
    {
      name: "get_cpi",
      description:
        "한국은행 ECOS에서 소비자물가지수(CPI, 월별) 데이터를 조회합니다.",
      inputSchema: {
        type: "object",
        properties: {
          startDate: {
            type: "string",
            description: "시작 월 (YYYYMM 형식, 예: 202301)",
          },
          endDate: {
            type: "string",
            description: "종료 월 (YYYYMM 형식, 예: 202412)",
          },
        },
        required: ["startDate", "endDate"],
      },
    },
    {
      name: "get_base_rate",
      description:
        "한국은행 기준금리(일별) 데이터를 ECOS에서 조회합니다.",
      inputSchema: {
        type: "object",
        properties: {
          startDate: {
            type: "string",
            description: "시작일 (YYYYMMDD 형식, 예: 20230101)",
          },
          endDate: {
            type: "string",
            description: "종료일 (YYYYMMDD 형식, 예: 20241231)",
          },
        },
        required: ["startDate", "endDate"],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const tool = request.params.name;
  const args = request.params.arguments;

  let rows = [];
  let label = "";

  if (tool === "get_gdp_growth") {
    rows = await fetchEcos("111Y002", "Q", args.startDate, args.endDate);
    label = "실질 GDP 성장률(%)";
  } else if (tool === "get_cpi") {
    rows = await fetchEcos("021Y002", "M", args.startDate, args.endDate, "0");
    label = "소비자물가지수";
  } else if (tool === "get_base_rate") {
    rows = await fetchEcos("722Y001", "D", args.startDate, args.endDate, "0101000");
    label = "한국은행 기준금리(%)";
  } else {
    throw new Error("Unknown tool: " + tool);
  }

  if (rows.length === 0) {
    return {
      content: [
        {
          type: "text",
          text: `${label} 데이터를 가져오지 못했습니다. 날짜 형식과 범위를 확인하세요.`,
        },
      ],
    };
  }

  const formatted = rows
    .map((r) => `${r.TIME}: ${r.DATA_VALUE}`)
    .join("\n");

  return {
    content: [
      {
        type: "text",
        text: `[${label}]\n${formatted}`,
      },
    ],
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);

package.json에 "type": "module"을 추가해야 ES 모듈 구문이 동작합니다.

{
  "name": "ecos-stats-mcp",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js"
}

4단계: 환경 변수에 ECOS API 키 설정

프로젝트 루트에 .env 파일을 만들어 API 키를 저장합니다.

touch .env
echo ".env" >> .gitignore

.env 파일 내용:

ECOS_API_KEY=발급받은_32자_ECOS_인증키_입력

Claude Desktop 설정 파일에서 직접 env 항목으로 키를 주입할 수도 있습니다(다음 단계 참조). .env 파일을 Git에 올리지 않도록 반드시 .gitignore에 포함하세요.

5단계: Claude Desktop 설정 파일에 MCP 서버 등록

Claude Desktop 설정 파일을 열어 ECOS 경제통계 MCP 서버를 추가합니다.

설정 파일 위치

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ecos-stats": {
      "command": "node",
      "args": ["/절대경로/ecos-stats-mcp/index.js"],
      "env": {
        "ECOS_API_KEY": "발급받은_ECOS_인증키_입력"
      }
    }
  }
}

/절대경로/ 부분을 실제 디렉터리 경로로 바꿔 주세요. macOS에서는 터미널에서 프로젝트 디렉터리 안에서 pwd를 실행하면 절대 경로를 확인할 수 있습니다.

설정 저장 후 Claude Desktop을 완전히 종료하고 다시 실행합니다.

6단계: GDP·물가·금리 조회 테스트

Claude Desktop을 재시작한 뒤 새 대화를 열고 아래 질문을 입력해 보세요.

2023년 1분기부터 2024년 4분기까지 분기별 실질 GDP 성장률을 표로 정리해줘

2023년 1월부터 2024년 12월까지 소비자물가지수 추이를 보여줘

2022년부터 2024년까지 한국은행 기준금리 변동 내역을 알려줘

ECOS에서 데이터를 가져와 Claude가 자연어와 표 형태로 답변하면 연동이 정상적으로 완료된 것입니다.

경제 리포트 자동화 예시

MCP 연동이 완료되면 단순 조회를 넘어 복합 분석도 가능합니다. 예를 들어 Claude에게 다음과 같은 요청을 할 수 있습니다.

“2022~2024년 기준금리 인상 시점과 소비자물가 상승률을 비교 분석하고, 통화정책 효과에 대한 의견을 덧붙여줘”
“최근 8분기 GDP 성장률 데이터를 바탕으로 경기 사이클을 진단하는 한 페이지 보고서를 작성해줘”
“물가·금리·환율 세 지표의 최근 1년 추이를 테이블로 요약하고, 상관관계를 설명해줘”

이처럼 데이터 수집·정리·분석·서술까지 Claude 한 곳에서 처리할 수 있는 것이 ECOS 경제통계 MCP의 핵심 가치입니다.

흔한 오류와 해결 방법

오류 증상	원인	해결 방법
”API 인증 실패” 또는 빈 응답	ECOS API 키 오류·미입력	`.env` 또는 설정 파일의 키 값 재확인, 공백 여부 점검
”데이터를 가져오지 못했습니다”	날짜 형식 또는 통계표 코드 오류	ECOS 문서에서 코드 확인, 형식 예시대로 입력
Claude에서 도구 목록 안 보임	설정 파일 JSON 문법 오류	JSON 유효성 검사기로 점검, 쉼표·따옴표 확인
”node: command not found”	Node.js 미설치 또는 경로 문제	Node.js 18 이상 설치, `which node`로 경로 확인
주말·공휴일 데이터 없음	ECOS 비영업일 데이터 미제공	영업일 날짜로 조회 기간 조정
일일 호출 한도 초과	1만 건/일 초과	불필요한 반복 호출 제거, 캐싱 로직 추가 고려

통계표 코드 오류 대처

ECOS API는 통계표 코드와 세부 항목 코드(item code)가 정확히 일치해야 데이터를 반환합니다. 코드를 모를 때는 ECOS 웹사이트 로그인 후 Open API 메뉴의 통계목록 조회 기능을 사용하거나, ECOS API 문서 페이지에서 검색하세요.

함께 쓰면 좋은 한국 금융 데이터 MCP 서버

ECOS 경제통계를 기업 재무·주식 데이터와 결합하면 더욱 풍부한 분석이 가능합니다. 아래 서버들을 함께 Claude Desktop에 등록해 보세요.

한국 주식 MCP 서버 — DART·KRX 공식 API로 국내 주가·재무 정보를 Claude에서 바로 분석합니다. ECOS 금리 데이터와 주가 움직임을 교차 분석할 때 유용합니다.
DART MCP 서버 — 상장기업 전자공시 재무제표를 Claude Code·Cursor에서 직접 불러올 수 있습니다. GDP 성장률과 개별 기업 실적을 함께 비교할 때 활용하세요.
한국 DART MCP — OpenDART 83개 API를 15개 MCP 도구로 압축해 공시·재무 분석에 최적화됐습니다.

금융 카테고리 전체 MCP 서버 목록에서 더 많은 한국 금융 데이터 연동 서버를 확인하고, 가이드 전체 목록에서 다른 금융 MCP 설정 방법도 참고해 보세요.

자주 묻는 질문

ECOS API 경제통계 MCP를 사용하려면 비용이 드나요?

한국은행 ECOS Open API 키 자체는 무료로 발급됩니다. 하루 최대 1만 건까지 무료 호출이 가능하며, 개인·연구 목적의 경제통계 조회에는 충분한 한도입니다. Claude는 사용 플랜에 따라 별도 요금이 적용됩니다.

ECOS API로 어떤 경제지표를 조회할 수 있나요?

GDP 성장률, 소비자물가지수(CPI), 생산자물가지수(PPI), 한국은행 기준금리, 콜금리, 국고채 수익률, 원달러 환율, M1·M2 통화량, 경상수지 등 한국은행이 공표하는 수백 개의 거시경제 시계열 데이터를 조회할 수 있습니다.

MCP로 연결한 ECOS 데이터는 실시간인가요?

ECOS API는 한국은행이 공식 공표한 통계 데이터를 제공합니다. 기준금리는 금통위 결정 직후, GDP 성장률은 분기별 잠정치 발표 후 수일 내에 업데이트됩니다. 분 단위 실시간 시세가 아니라 공식 통계 발표 기준임을 유의하세요.

Claude Desktop과 Claude Code 중 어디에서 설정하나요?

두 환경 모두 MCP를 지원합니다. Claude Desktop은 claude_desktop_config.json을 수정해 연결하고, Claude Code는 프로젝트 루트의 .mcp.json 파일로 추가합니다. 개인 경제 분석 목적이라면 Claude Desktop이 더 간편합니다.

GDP 통계표 코드는 어디서 찾나요?

ECOS 웹사이트(ecos.bok.or.kr) 로그인 후 Open API 메뉴의 ‘통계목록 조회’에서 원하는 지표의 통계표 코드를 확인할 수 있습니다. 예를 들어 실질 GDP 성장률은 111Y002, 소비자물가지수는 021Y002, 기준금리는 722Y001입니다.

ECOS 데이터를 DART 재무제표와 함께 분석할 수 있나요?

네, 가능합니다. Claude Desktop에 ECOS 경제통계 MCP와 DART MCP 서버를 함께 등록하면 “삼성전자 영업이익 추이를 GDP 성장률 변화와 비교 분석해줘” 같은 교차 분석 질문이 가능합니다.

다음 단계

ECOS 경제통계 MCP 연동에 성공했다면, 이제 더 고도화된 분석에 도전해 보세요. 한국 주식 MCP 서버와 DART MCP 서버를 함께 등록하면 거시경제 지표와 개별 기업 실적을 Claude 한 곳에서 교차 분석하는 본격적인 AI 경제 분석 환경을 갖출 수 있습니다.

더 많은 한국 금융 MCP 서버를 탐색하려면 금융 카테고리 페이지를 방문하거나, MCP 서버 전체 목록에서 다양한 국내 API 연동 서버를 찾아보세요. 직접 개발한 ECOS 관련 MCP 서버가 있다면 MCP모아에 등록해 한국 개발자 커뮤니티와 공유해 주세요.