Finance MCP Server

Claude(Cowork/Desktop)의 WebSearch·WebFetch가 차단당하거나(네이버 금융) 못 가져오는(CoinGecko 등) 금융 시세를, 로컬에서 실행되는 MCP 서버의 Tool 호출로 안정적·정규화된 형태로 조회한다. 데일리 투자 리포트의 시세 정확도 보장이 목적이다.

Tool 목록

티커 형식

• 국내 주식/ETF: 6자리 코드 (005930, 381180) → 네이버 polling
• 해외 주식/지수: Yahoo 심볼 (^GSPC, ^IXIC, ^SOX, AAPL) → Yahoo chart API
• 환율: USD/KRW (Yahoo KRW=X)
• 크립토: 심볼 + quote (BTC/KRW, ETH/USD) → CoinGecko

응답 스키마

성공:

{"name":"KOSPI","value":9165.58,"change":113.16,"change_pct":1.25,
 "timestamp":"2026-06-22T11:27:14+09:00","currency":"KRW","source":"naver"}

실패(Claude가 WebSearch로 폴백):

{"name":"KOSPI","error":"timeout","source":"fallback"}

소스 우선순위 (자동 강등)

상위 실패 시 다음 소스로 자동 강등, 전부 실패 시 {error, source:"fallback"}.

설치

py -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
# (선택) 최후 수단 렌더링 fallback
.venv\Scripts\python -m pip install playwright && .venv\Scripts\python -m playwright install chromium

사내망(TLS 가로채기) 환경 주의

일부 사내망은 TLS를 가로채(MITM) 사내 루트 CA로 재서명한다. 이 CA는 Windows 인증서 저장소에만 있고 Python(certifi)엔 없어 기본 검증이 실패한다. 본 서버는 truststore로 OS 인증서 저장소를 사용해 검증을 유지하면서 사내 CA도 신뢰한다(requirements에 포함). 사내망에서 동작 확인됨.

Claude Desktop 연동

claude_desktop_config.json:

{
  "mcpServers": {
    "finance": {
      "command": "C:\\Chamomile\\workspace\\agentHwang\\finaceMcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Chamomile\\workspace\\agentHwang\\finaceMcp\\finance_server.py"],
      "env": { "EXIM_API_KEY": "", "FINNHUB_KEY": "" }
    }
  }
}

환경변수 (선택)

.env 또는 config의 env로 주입. 없으면 해당 소스는 건너뛴다.

• EXIM_API_KEY: 한국수출입은행 환율 API(가정용 PC 환율 폴백).
• FINNHUB_KEY: 미국 주식 폴백(예약, 현재 미사용).
• MOLIT_API_KEY: 국토교통부 실거래가 API(get_apt_trade/get_apt_rent에 필수).

부동산 실거래가 사용법

1. 공공데이터포털에서 "국토교통부_아파트 매매 실거래가 자료",

"국토교통부_아파트 전월세 실거래가 자료" 활용신청(무료).

1. 마이페이지 → 인증키에서 Decoding(일반) 키를 복사해 MOLIT_API_KEY에 설정

(Encoding 키를 쓰면 이중 인코딩으로 인증 실패).

1. region_code는 5자리 시군구 법정동코드(예: 강남구 11680, 송파구 11710).

전체 목록은 행정표준코드관리시스템(code.go.kr)의 법정동코드 참고.

1. deal_amount/deposit/monthly_rent 단위는 만원. 예: deal_amount=250000 → 25억.
2. deal_ym은 "YYYYMM"/"YYYY-MM" 모두 허용. 평당가는 전용면적 기준(공급면적

기준 시장 평당가보다 높게 나옴).

#### months 옵션 (집계 Tool) get_apt_trade_summary·get_jeonse_ratio는 months로 기준월 포함 직전 N개월(기본 1, 최대 12)을 합산해 표본을 늘린다. 단일 월은 거래가 적어 평균이 흔들리거나(평당가 집계), 같은 달에 매매·전세가 모두 난 단지만 매칭돼(전세가율) 표본이 적다. months=3~6 권장.

# 단일 월
get_apt_trade_summary("강남구", "2026-04")            # 411건 / 165단지
get_jeonse_ratio("강남구", "2026-04")                 # 86단지 매칭

# 6개월 합산 (period: "202511~202604")
get_apt_trade_summary("강남구", "2026-04", months=6)  # 1,442건 / 327단지
get_jeonse_ratio("강남구", "2026-04", months=6)       # 250단지 매칭, 평균 전세가율 43.6%

반환에 months와 합산 구간 period 필드가 포함된다. get_apt_trade/get_apt_rent (원시 거래 조회)는 단일 월만 지원한다.

API별 활용신청 필요: 매매(get_apt_trade)와 전월세(get_apt_rent)는 별개 API다. 둘 다 쓰려면 data.go.kr에서 각각 활용신청해야 한다(한쪽만 신청 시 다른 쪽은 403). data.go.kr WAF가 curl 기본 UA를 차단하므로 서버는 브라우저 UA로 호출한다(코드 내 처리됨). 응답 XML은 stdlib로 파싱하며 전월세 필드는 실데이터로 검증됨(2026-06-22).

비기능

• 메모리 TTL 캐시 30초(동일 키 중복 호출 방지)
• 호출당 5초 타임아웃, 1순위 1회 재시도 후 강등
• 전 Tool 예외 포착 → fallback 반환(서버 크래시 없음)
• 로그는 stderr만(stdout은 MCP 전용)

테스트

.venv\Scripts\python -m pytest -q

HTTP는 respx로 모킹한다(네트워크 불필요).

비대상 (Non-Goals)

매매/계좌 연동, 실시간 스트리밍, DB 영속화, 차트 이미지 생성.