Finance MCP Server

English version

LLM 에이전트를 위한 개인용 금융 리서치·실행 툴킷입니다. DART, Telegram, Toss증권이라는 세 가지 소스를 하나로 묶은 MCP 서버로 구현했습니다.

왜 이 세 가지인가

대부분의 "AI + 금융" 프로젝트는 시세 API, 뉴스 피드, 증권사 연동 중 하나만 붙입니다. 이 프로젝트는 제대로 된 금융 판단을 하려면 성격이 서로 다른 세 가지 입력이 필요하다는 전제에서 출발했습니다. 각자 가장 잘하는 역할만 맡깁니다.

• DART — 정형 데이터 (structured data). 한국의 공식 전자공시 시스템 (공시서류, 재무제표, 지분 구조, 배당). 감사받고 날짜가 찍힌, 명확한 사실(ground truth)입니다. 다만 태생적으로 느리고 과거지향적입니다 — 직전 분기 보고서일 뿐, 지금 이 순간 일어나는 일은 아닙니다.

• Telegram — 비정형 데이터 (unstructured data). 단순히 "뉴스 대체재"로 고른 게 아니라 의도적으로 선택했습니다. 애널리스트와 개인 투자자들이 매일 자신의 리서치와 의견을 텔레그램에 올립니다 — 국내 주식 투자 커뮤니티에서 비공식적으로, 정식 발간 전에 오가는 정보 상당수가 실제로 여기서 일어납니다. 목적은 "뉴스 헤드라인을 더 많이 긁어오는 것"이 아니라, 실제로 매매하는 사람들이 지금 이 순간 무엇에 주목하고 있는지를 보는 것입니다 — 이는 어떤 뉴스 통신사가 전하는 것과는 다른 종류의 신호입니다.

• Toss증권 — 실행 계층 (execution layer). 시세, 호가, 캔들, 계좌 보유 현황 — 그리고 점점 더, 실제로 행동할 수 있는 능력: 실거래 주문의 제출·정정· 취소, 포트폴리오 관리. 리서치가 실제 포지션으로 바뀌는 지점입니다.

정리하면: DART는 무엇이 사실인지 알려주고, Telegram은 사람들이 지금 무엇에 주목하는지 알려주며, Toss는 그 둘을 바탕으로 실제 행동에 옮기는 수단입니다.

아키텍처

각 소스는 그 자체로 완결된, 독립적으로도 동작하는 MCP 서버입니다.

finance-mcp-server/
├── server.py       # 아래 세 서버를 하나의 MCP 서버로 합칩니다
├── dart/           # 정형 데이터
├── toss/           # 실행 계층
└── telegram/       # 비정형 데이터

루트의 server.py는 세 서버의 로직을 복제하거나 다시 구현하지 않습니다. 임포트 시점에 각 <source>/server.py를 독립된 모듈로 불러온 뒤, 거기 등록된 툴들을 하나의 공유 MCP 서버 인스턴스에 그대로 복사해 옵니다. 즉 특정 툴의 동작을 바꾸고 싶으면 그 툴이 속한 소스 폴더 안에서 수정하면 됩니다 — 루트 파일은 그저 연결만 담당하며, 소스 쪽 변경 사항은 다음 재시작 때 자동으로 반영됩니다.

세 서버 모두에서 유일하게 겹치는 이름은 test_connection입니다 (셋 다 자체적으로 하나씩 가지고 있습니다). 이들은 각각 dart_test_connection, toss_test_connection, telegram_test_connection으로 이름을 바꿔 등록했습니다. 그 외 이름은 모두 원래 그대로 고유합니다. 세 소스의 자격증명/연결 상태를 한 번에 확인하는 finance_test_connection 툴도 추가했습니다.

빠른 시작

각 소스는 자체 자격증명이 필요합니다 — 소스별 설정 방법(Toss의 IP 화이트리스트 요건, Telegram의 최초 1회 로그인 포함), 전체 툴 목록, 사용 예시는 USAGE.md를 참고하세요.

# 사용하려는 dart/, toss/, telegram/ 각각에서:
cp .env.example .env   # 실제 값으로 채우기

# 저장소 루트에서:
uv sync
uv run server.py

MCP 클라이언트에 등록하기

{
  "mcpServers": {
    "finance-mcp": {
      "command": "/절대경로/finance-mcp-server/.venv/bin/python",
      "args": ["/절대경로/finance-mcp-server/server.py"]
    }
  }
}

실거래 주문 기능 (Toss)

place_order와 modify_order는 실제 계좌에 진짜 주문을 제출하며, 명시적으로 confirm=True를 넘겨야만 동작합니다 — 넘기지 않으면 아무것도 제출하지 않고 에러를 냅니다. 일정 금액 이상의 주문은 confirm_high_value_order=True까지 추가로 요구합니다. cancel_order는 의도적으로 confirm=True 게이트가 없습니다 — 취소는 안전한 방향의 행동이기 때문입니다. 이 중 어느 것도 "사람의 최종 확인"을 대체하지는 않습니다: 자율적으로 동작하는 에이전트가 스스로 confirm=True를 넘길 수도 있으므로, 이는 사람이 승인했다는 증거가 아니라 호출자의 의도를 기록하는 정도로 받아들여야 합니다. 시뮬레이션/모의 투자 모드는 없습니다. 자율적으로 툴을 호출할 수 있는 환경에 연결하기 전에 반드시 toss/README.md를 읽어보세요.

문서

• USAGE.md — 소스별 전체 설정 방법, 전체 툴 목록, 사용 예시
• DESIGN.md — 각 소스의 안전장치가 지금 형태로 설계된 이유: DART/Telegram의 제한(데이터 양을 제한)과 Toss의 제한(되돌릴 수 없는 행동을 제한)이 서로 어떻게 다른지, 그리고 공개 전 보안 점검으로 무엇이 바뀌었는지

현재 상태

이 프로젝트는 계속 진화 중인 개인 프로젝트이며, 완성된 제품이 아닙니다. 세 소스 각각은 독립적으로 만들고 다듬어진 뒤 이렇게 합쳐졌습니다. 다듬어지지 않은 부분이 있을 수 있고, 특히 Toss 쪽을 중심으로 툴 목록은 계속 늘어날 것으로 예상합니다.

라이선스

MIT