M MCP모아
튜토리얼

환율 MCP 서버로 Claude에서 실시간 환율 조회하는 방법

환율 MCP 서버를 Claude Desktop·Claude Code에 연결해 실시간 달러·엔·유로 환율을 AI로 즉시 조회하는 방법을 단계별로 안내합니다. ECOS 환율 API 연동 포함.

Claude Desktop에서 환율 MCP 서버를 통해 실시간 달러·엔 환율을 조회하는 화면

Claude에 환율 MCP 서버를 연결하면 별도 탭을 열지 않아도 대화 중에 “오늘 달러 환율 얼마야?”라고 물어보는 것만으로 즉시 답을 받을 수 있습니다. 이 가이드에서는 한국은행 ECOS API를 활용하는 환율 MCP 서버를 Claude Desktop에 단계별로 연결하는 방법을 설명합니다. API 키 발급부터 설정 파일 작성, 동작 확인까지 30분 안에 완료할 수 있습니다.

환율 MCP 서버가 필요한 이유

재무 분석, 해외 결제, 수출입 업무를 Claude와 함께 처리하다 보면 환율 정보를 매번 따로 찾아야 하는 불편함이 생깁니다. 일반 ChatGPT나 Claude의 기본 상태에서는 실시간 환율을 알 수 없고, 인터넷 검색 기능이 있어도 원하는 통화 쌍 데이터를 정확히 가져오지 못할 때가 있습니다.

MCP(Model Context Protocol)는 AI 어시스턴트가 외부 도구와 데이터 소스를 표준화된 방식으로 연결하게 해주는 프로토콜입니다. 환율 MCP 서버를 설치하면 Claude가 한국은행 ECOS API를 직접 호출해 최신 환율 데이터를 가져오고, 그 값을 기반으로 계산·분석·보고서 작성까지 이어서 처리할 수 있습니다.

MCP 연결 후 데이터 흐름

사용자 질문
    │
    ▼
Claude Desktop (MCP 클라이언트)
    │  MCP 프로토콜 (JSON-RPC)
    ▼
환율 MCP 서버 (로컬 프로세스)
    │  HTTP REST
    ▼
한국은행 ECOS 오픈 API
    │  JSON 응답
    ▼
Claude가 환율 데이터 해석 → 사용자 답변

준비물

항목설명필수 여부
Claude DesktopAnthropic 공식 데스크톱 앱필수
Node.js 18 이상MCP 서버 실행 환경필수
ECOS API 키한국은행 경제통계시스템 발급필수
Git저장소 클론필수
터미널(macOS/Windows)명령어 실행필수

Claude Desktop은 claude.ai/download에서 무료로 설치할 수 있습니다. ECOS API 키는 아래 1단계에서 발급합니다.

단계별 설치 방법

1단계: 한국은행 ECOS API 키 발급

한국은행 경제통계시스템(ecos.bok.or.kr)에서 무료 API 키를 발급받습니다.

  1. https://ecos.bok.or.kr 접속 후 회원가입
  2. 로그인 후 상단 메뉴에서 오픈 API 클릭
  3. 인증키 신청 메뉴에서 사용 목적을 입력하고 신청
  4. 발급된 인증키(32자 영숫자)를 안전한 곳에 복사

발급은 보통 당일 또는 다음 영업일 이내에 완료됩니다. 이메일로 발급 완료 알림이 옵니다.

2단계: 환율 MCP 서버 설치 및 준비

현재 ECOS 환율 데이터를 직접 활용하는 MCP 서버는 커뮤니티에서 개발 중이거나 로컬 직접 구성 방식으로 운영됩니다. 가장 현실적인 방법은 한국은행 ECOS API를 감싸는 MCP 서버를 직접 구성하거나, 아래와 같이 범용 HTTP MCP 브리지를 활용하는 것입니다.

아래는 ECOS REST API를 직접 호출하는 간단한 MCP 서버 구성 예시입니다. Node.js 환경에서 동작합니다.

# 작업 디렉터리 생성
mkdir ecos-exchange-mcp && cd ecos-exchange-mcp

# package.json 초기화
npm init -y

# MCP SDK 설치
npm install @modelcontextprotocol/sdk node-fetch

3단계: 환경 변수 설정

프로젝트 루트에 .env 파일을 생성하고 ECOS API 키를 저장합니다.

# .env 파일 생성
touch .env
ECOS_API_KEY=여기에_발급받은_32자_인증키_입력

보안을 위해 .env 파일을 .gitignore에 추가하세요.

echo ".env" >> .gitignore

4단계: MCP 서버 코드 작성

index.js 파일을 생성하고 아래 코드를 작성합니다. ECOS API의 외환 통계(통계표 코드: 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";

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

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_exchange_rate",
      description:
        "한국은행 ECOS API에서 원화 기준 환율을 조회합니다. 통화 코드(USD, JPY, EUR 등)와 날짜를 입력하세요.",
      inputSchema: {
        type: "object",
        properties: {
          currency: {
            type: "string",
            description: "통화 코드 (예: USD, JPY, EUR, CNY)",
          },
          date: {
            type: "string",
            description: "조회 날짜 (YYYYMMDD 형식, 생략 시 최근 영업일)",
          },
        },
        required: ["currency"],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_exchange_rate") {
    const currency = request.params.arguments.currency;
    const today = new Date().toISOString().slice(0, 10).replace(/-/g, "");
    const date = request.params.arguments.date || today;

    const url =
      `${ECOS_BASE}/StatisticSearch/${ECOS_API_KEY}/json/kr/1/5/` +
      `731Y001/D/${date}/${date}/${currency}`;

    const res = await fetch(url);
    const data = await res.json();

    const rows = data?.StatisticSearch?.row;
    if (!rows || rows.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `${currency} 환율 데이터를 조회할 수 없습니다. 날짜가 영업일인지 확인하세요.`,
          },
        ],
      };
    }

    const rate = rows[0];
    return {
      content: [
        {
          type: "text",
          text: `${rate.ITEM_NAME1} 환율 (${rate.TIME}): ${rate.DATA_VALUE} 원`,
        },
      ],
    };
  }
  throw new Error("Unknown tool");
});

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

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

Claude Desktop의 설정 파일을 열어 MCP 서버를 추가합니다.

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "ecos-exchange": {
      "command": "node",
      "args": ["/절대경로/ecos-exchange-mcp/index.js"],
      "env": {
        "ECOS_API_KEY": "여기에_ECOS_API_키_입력"
      }
    }
  }
}

/절대경로/ 부분을 실제 프로젝트 경로로 변경하세요. macOS에서는 pwd 명령으로 현재 경로를 확인할 수 있습니다.

6단계: Claude Desktop 재시작 및 동작 확인

설정 저장 후 Claude Desktop을 완전히 종료하고 다시 시작합니다. 그런 다음 채팅창에 아래와 같이 입력해 보세요.

오늘 달러(USD) 환율 알려줘

Claude가 ECOS API를 호출해 최신 고시 환율을 응답하면 연결이 정상적으로 완료된 것입니다. 유로(EUR), 일본 엔(JPY), 중국 위안(CNY) 등 다른 통화도 동일하게 조회할 수 있습니다.

흔한 오류와 해결 방법

오류 증상원인해결 방법
”Unknown tool” 오류서버가 도구 목록을 못 내려줌JSON 문법 오류 확인, 서버 로그 점검
환율 데이터 없음주말·공휴일 날짜 조회전날 또는 최근 영업일로 날짜 변경
ECOS API 인증 실패API 키 오류 또는 미발급.env 또는 설정 파일의 키 값 재확인
MCP 서버 연결 안 됨파일 경로 오류절대 경로로 수정, 파일 존재 여부 확인
node 명령 인식 안 됨Node.js 미설치Node.js 18 이상 설치 후 재시도

ECOS API는 조회 횟수 제한(일 1만 건)이 있습니다. 일반 개인 사용자는 거의 초과하지 않지만, 자동화 스크립트로 대량 호출 시에는 캐싱을 고려하세요.

환율 MCP와 함께 쓰면 좋은 금융 MCP 서버

환율 데이터만으로는 부족할 때 아래 서버를 함께 설치하면 Claude 안에서 종합적인 금융 데이터 분석이 가능합니다.

  • 한국 주식 MCP 서버 — DART·KRX 공식 API로 국내 주식 시세, 재무 정보를 Claude에서 바로 조회합니다.
  • DART MCP 서버 — 상장기업 재무제표·공시를 Claude Code·Cursor에서 직접 불러올 수 있습니다.
  • 한국 DART MCP — OpenDART 83개 API를 15개 MCP 도구로 압축해 재무·공시 분석에 최적화됐습니다.

금융 카테고리 전체 MCP 서버 목록에서 다른 금융 API 연동 서버도 찾아볼 수 있습니다.

자주 묻는 질문

ECOS API 키는 무료로 발급받을 수 있나요?

네, 한국은행 경제통계시스템의 오픈 API는 개인 및 비영리 목적으로 무료입니다. ecos.bok.or.kr에서 회원가입 후 신청하면 당일 또는 다음 영업일에 발급됩니다.

환율 데이터가 얼마나 자주 갱신되나요?

ECOS에서 제공하는 외환 데이터는 기본적으로 영업일 기준 일별 데이터이며, 당일 서울 외환시장 마감 기준으로 업데이트됩니다. 분 단위 실시간 호가가 필요하다면 별도의 외환 API를 검토해야 합니다.

Claude Code와 Claude Desktop 중 어디에 연결해야 하나요?

두 환경 모두 MCP 서버를 지원합니다. 개인 분석 용도라면 Claude Desktop이 더 간편하며, 개발 워크플로우에 통합하려면 Claude Code를 선택하세요. Claude Code에서는 프로젝트 루트의 .mcp.json 파일로 설정합니다.

환율 MCP 서버가 지원하는 통화 쌍은 어디서 확인하나요?

ECOS 오픈 API 문서(ecos.bok.or.kr)의 통계표 코드 731Y001(외환) 항목에서 지원 통화 목록을 확인할 수 있습니다. USD, JPY, EUR, CNY 등 주요 통화를 포함합니다.

MCP 서버 연결 후 Claude가 환율 도구를 찾지 못하는 경우 어떻게 하나요?

Claude Desktop을 완전히 종료하고 재시작하세요. 그래도 해결되지 않으면 claude_desktop_config.json의 JSON 문법 오류 여부를 확인하고, 서버 실행 경로가 올바른지 점검하세요. 터미널에서 직접 node /경로/index.js를 실행해 오류 메시지를 확인하는 것도 좋습니다.

환율 외에 주식·공시 데이터도 Claude에서 조회할 수 있나요?

네, 가능합니다. 한국 주식 MCP 서버와 DART MCP 서버를 추가로 설치하면 환율과 주식·재무 정보를 Claude 한 곳에서 함께 분석할 수 있습니다.

다음 단계

환율 MCP 서버 연결이 완료됐다면, 이제 Claude에게 더 복잡한 질문을 던져보세요. “지난 달 대비 달러 환율 변화와 삼성전자 주가 상관관계를 분석해줘”처럼 환율과 주식 데이터를 함께 분석하는 것도 가능합니다. 금융 카테고리의 다른 MCP 서버들을 조합해 나만의 AI 금융 분석 환경을 구성해 보세요.

MCP 서버를 직접 개발하셨거나 유용한 환율 관련 서버를 알고 계신다면 MCP모아에 등록해 한국 개발자 커뮤니티와 공유해 주세요.

이 글과 관련된 MCP 서버