MCP 서버 — AI 에이전트·AI 트레이딩 봇을 위한 FX 펀더멘털 API

빠른 시작 (Claude Desktop / Claude Code)

MCP 클라이언트에서 사용하는 최단 셋업입니다. 약 3분이면 완료됩니다.

전제 조건

MCP 클라이언트를 미리 준비해 주십시오.

Claude Desktop: https://claude.ai/download 에서 다운로드 및 설치
Claude Code (CLI): npm install -g @anthropic-ai/claude-code 등으로 설치된 터미널에서 사용 가능
Cursor / Windsurf 등: MCP를 지원하는 버전을 사용

1

FundaFX 모바일 앱을 설치하고 API 키 받기 (필수)

FundaFX의 API 키는 모바일 앱에서만 발급 및 관리됩니다. Free 등급(100 req/월)도 Pro 구독(5,000 req/월)도 앱을 통해 제공됩니다.

iOS: App Store에서 다운로드
Android: Google Play 출시 준비 중

앱 실행 후 설정 > API 키 관리에서 fndx_로 시작하는 키를 복사하세요.

2

MCP 클라이언트에 등록

아래 "셋업" 섹션을 참고하세요. Claude Desktop은 설정 파일(~/Library/Application Support/Claude/claude_desktop_config.json 등)에 JSON을 붙여넣고, Claude Code는 claude mcp add CLI 명령 한 줄로 등록할 수 있습니다. fndx_your_api_key_here를 받은 키로 교체해 주세요.

3

클라이언트를 재시작하고 질문하기

Claude Desktop은 재시작 후, Claude Code는 새 세션에서 활성화됩니다. "FED의 금리는?" "USD 관련 중요 사실 가져와" 등 자연어로 묻기만 하면 에이전트가 적절한 도구를 자동으로 호출합니다.

셋업

MCP 클라이언트의 설정 파일에 다음을 추가해 주세요.

Claude Desktop (JSON 설정)

설정 파일 위치:
· macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
· Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "fundafx": {
      "command": "npx",
      "args": ["fundafx-mcp-server"],
      "env": {
        "FUNDAFX_API_KEY": "fndx_your_api_key_here",
        "FUNDAFX_API_URL": "https://api.fundafx.link"
      }
    }
  }
}

Claude Code (CLI 명령)

Claude Code에서는 전용 claude mcp add 명령으로 등록할 수 있어 JSON을 직접 작성할 필요가 없습니다. --scope user를 추가하면 모든 프로젝트에서 참조 가능해집니다(프로젝트 한정으로 하려면 생략).

터미널

claude mcp add fundafx \
  --scope user \
  --env FUNDAFX_API_KEY=fndx_your_api_key_here \
  --env FUNDAFX_API_URL=https://api.fundafx.link \
  -- npx fundafx-mcp-server

등록 확인: claude mcp list. 상태가 ✓ Connected로 표시되면 OK입니다.

Cursor / Windsurf 등 다른 클라이언트

Cursor, Windsurf 등 기타 MCP 지원 클라이언트도 위 "Claude Desktop (JSON 설정)"과 동일한 JSON을 각 클라이언트의 MCP 설정란에 붙여넣어 사용할 수 있습니다.

Python MCP 서버 (로컬)

claude_desktop_config.json

{
  "mcpServers": {
    "fundafx": {
      "command": "uv",
      "args": ["run", "python", "-m", "fundafx.mcp.run"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://..."
      }
    }
  }
}

환경 변수

변수	설명	기본값
FUNDAFX_API_KEY	API 키 (TypeScript 버전에서 필요)	—
FUNDAFX_API_URL	API 베이스 URL	`http://localhost:8000`
DATABASE_URL	PostgreSQL 접속 문자열 (Python 버전에서 필요)	—

사용 가능한 도구

MCP 서버는 4개의 도구를 제공합니다. LLM이 문맥에 따라 자동으로 최적의 도구를 선택하므로, 여러분은 자연어로 질문만 하면 됩니다.

과거 데이터(시계열)를 조회하려면 별도 도구가 아닌, get_indicator_analysis의 include_history=true 옵션을 사용하세요.

get_facts READ

FX 펀더멘털 팩트를 검색합니다. 경제 이벤트, 통화정책 결정, 데이터 발표, 시장 관련 뉴스를 필터로 조회합니다. 이벤트 타임스탬프 최신순으로 반환됩니다.

Parameters

이름	타입	설명
currency	string 선택	통화 코드: `USD`, `EUR`, `JPY`, `GBP`, `AUD`, `CAD`, `CHF`, `NZD`, `CNY`
fact_type	string 선택	`institutional_release`, `official_speech`, `media_report`
importance	string 선택	`high`, `medium`, `low`
source_collector	string 선택	수집 출처: `cb_rss`, `ecb`, `gdelt`, `news_rss` 등
limit	int 선택	가져올 항목 수 (1-100, 기본값 20)

사용 예 (자연어)

"최신 고중요도 팩트를 5건 가져와 줘"
"EUR 관련 통화정책 뉴스를 보여 줘"
"이번 주 USD 관련 데이터 발표를 확인"
"GDELT에서 수집된 지정학 뉴스를 알려 줘"
"어제의 JPY 관련 뉴스를 정리해 줘"

get_indicator_analysis READ

특정 경제지표의 상세 분석을 가져옵니다. 최신 값, 메타데이터(단위, 빈도, 카테고리)와 선택적으로 과거 데이터를 포함합니다.

Parameters

이름	타입	설명
indicator	string 필수	지표 코드: `US_CPI`, `US_NFP`, `US_UNEMPLOYMENT`, `JP_GDP`, `EU_HICP`, `GB_CPI` 등
include_history	boolean 선택	과거 데이터 포인트 포함 (기본 false)

지표 코드는 <COUNTRY>_<INDICATOR> 형식(ISO 2글자 국가 코드 + 지표명)입니다. 예: 미국 CPI = US_CPI, 일본 GDP = JP_GDP. 존재하지 않는 코드를 지정하면 에러 응답에 사용 가능 코드 목록이 포함됩니다.

사용 예 (자연어)

"미국 CPI의 최근 12개월 추이를 보여 줘"
"일본 GDP 성장률의 시계열 데이터 가져와"
"미국의 비농업 부문 고용지수(NFP) 최신 데이터 알려 줘"

get_central_bank_sentiment READ

지정한 중앙은행의 현재 정책금리, 다음 회의일, 총재 정보를 가져옵니다. 통화정책 스탠스 파악에 유용합니다.

Parameters

이름	타입	설명
bank	string 필수	중앙은행 코드: `FED`, `ECB`, `BOJ`, `BOE`, `RBA`, `BOC`, `SNB`, `RBNZ`, `PBOC`

사용 예 (자연어)

"FED의 현재 금리와 다음 회의일을 알려 줘"
"ECB의 총재는 누구야?"
"BOJ의 정책금리는?"

get_rate_differentials READ

통화쌍 간의 금리차를 가져옵니다. 중앙은행의 정책금리와 그 스프레드를 표시합니다 — 캐리 트레이드 분석에 유용.

Parameters

이름	타입	설명
base	string 선택	기준 통화 코드: `USD`, `EUR`, `JPY`, `GBP`, `AUD`, `CAD`, `CHF`, `NZD`, `CNY` (생략 시 모든 통화)
quote	string 선택	호가 통화 코드 (위와 동일한 목록. 생략 시 모든 통화)

사용 예 (자연어)

"USD와 JPY의 금리차는 얼마야?"
"캐리 트레이드에 최적인 통화쌍을 분석해 줘"
"모든 중앙은행의 금리차를 한눈에 보여 줘"

활용 예

FundaFX MCP 서버의 대표적인 사용 사례.

봇 트레이딩

경제지표 발표 전후 포지션을 조정하는 봇에 실시간 팩트 데이터와 캘린더 이벤트를 공급합니다.

리서치 자동화

LLM 에이전트에 "이번 주 EUR 관련 뉴스를 정리해 줘"라고 지시하기만 하면 팩트 데이터 기반의 리포트를 자동으로 생성합니다.

포트폴리오 분석

금리차 매트릭스와 경제지표 추이를 결합하여 통화 배분 최적화를 AI에 위임합니다.

알림 시스템

캘린더 이벤트의 자동 모니터링과 중요 팩트 발생 시 알림 트리거를 에이전트를 통해 구현합니다.

마켓 브리핑

매일 아침의 마켓 요약을 자동 생성합니다. 전일의 중요 이벤트와 당일 일정을 구조화된 데이터에서 요약합니다.

백테스트 지원

과거 경제지표 값과 팩트 데이터를 가져와 트레이딩 전략의 백테스트에 필요한 펀더멘털 데이터를 공급합니다.

대화 예시

Claude Desktop에서 FundaFX MCP를 사용한 대화 예시.

Claude Desktop

User:
FED의 현재 금리와 주요 통화쌍의 금리차를 알려 줘.

Claude (MCP tool calls):
get_central_bank_sentiment(bank="FED")
get_rate_differentials(base="USD")

Claude:
FED(미국 연방준비제도이사회)의 상황:
- 현재 정책금리: 4.50%
- 의장: Jerome Powell
- 다음 FOMC: 2026-03-18

USD 기준 주요 통화쌍의 금리차:
  USD/JPY: +4.00% (4.50% - 0.50%)
  USD/EUR: +1.35% (4.50% - 3.15%)
  USD/GBP: +0.00% (4.50% - 4.50%)
  USD/AUD: +0.40% (4.50% - 4.10%)
  USD/CAD: +1.25% (4.50% - 3.25%)
  USD/CHF: +4.00% (4.50% - 0.50%)

데이터 소스

MCP를 통해 가져오는 데이터는 아래 12개 출처에서 수집됩니다.

출처	종류	데이터 내용
ECB	API	정책금리, 환율, 거시 통계
FRB	RSS	FOMC 성명, 연설, 보도자료
e-Stat	API	일본 경제 통계 (CPI, GDP 등)
OECD	API	주요국의 거시경제 지표
World Bank	API	각국 GDP, 인구, 개발 지표
EIA	API	원유·에너지 통계
CFTC	API	투기세력 포지션 (COT 리포트)
GDELT	API	글로벌 뉴스 이벤트
CB RSS	RSS	각국 중앙은행의 공식 발표
News RSS	RSS	주요 금융 뉴스
X (Twitter)	API	주요 인사·공식 기관의 게시물
Treasury Yields	API	미국채 금리

FAQ

MCP와 REST API의 차이점은?

REST API는 HTTP 요청으로 데이터를 직접 가져오는 전통적 인터페이스입니다. MCP는 LLM 에이전트가 자연어 문맥에서 적절한 도구를 자동 선택해 호출하는 프로토콜입니다. 내부적으로는 MCP 서버가 REST API를 호출합니다.

레이트 리밋은 어떻게 적용되나요?

MCP 서버를 경유한 요청에도 REST API와 동일한 레이트 리밋이 적용됩니다. Free 등급은 100회/월, Pro 등급은 5,000회/월입니다. 카운터는 매월 리셋됩니다.

TypeScript 버전과 Python 버전의 차이점은?

TypeScript 버전(npx fundafx-mcp-server)은 REST API를 통해 동작하는 원격 클라이언트입니다. Python 버전은 DB에 직접 접속하므로 셀프 호스트 환경용입니다. 일반 사용자는 TypeScript 버전을 권장합니다.

지원되는 클라이언트는?

MCP 프로토콜을 지원하는 모든 클라이언트에서 사용할 수 있습니다. Claude Desktop, Claude Code, Cursor, Windsurf 등에서 동작 확인 완료. Claude Desktop은 JSON 설정으로, Claude Code는 claude mcp add 명령으로 각각 등록할 수 있습니다("셋업" 섹션 참조).

FundaFX 모바일 앱은 필수인가요?

네. API 키의 발급·재발급·무효화, 그리고 Pro 플랜 구독은 모두 모바일 앱에서 진행됩니다. MCP 서버를 사용하려면 사전에 앱을 설치해 키를 받아 주세요(iOS는 App Store에서, Android는 Google Play 출시 준비 중).

MCP 서버 문서

빠른 시작 (Claude Desktop / Claude Code)

전제 조건

FundaFX 모바일 앱을 설치하고 API 키 받기 (필수)

MCP 클라이언트에 등록

클라이언트를 재시작하고 질문하기

셋업

Claude Desktop (JSON 설정)

Claude Code (CLI 명령)

Cursor / Windsurf 등 다른 클라이언트

Python MCP 서버 (로컬)

환경 변수

사용 가능한 도구

활용 예

봇 트레이딩

리서치 자동화

포트폴리오 분석

알림 시스템

마켓 브리핑

백테스트 지원

대화 예시

데이터 소스

FAQ

MCP와 REST API의 차이점은?

레이트 리밋은 어떻게 적용되나요?

TypeScript 버전과 Python 버전의 차이점은?

지원되는 클라이언트는?

FundaFX 모바일 앱은 필수인가요?