# Finance MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[English version](https://github.com/mkkim2102/finance-mcp-server)

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

## 왜 이 세 가지인가

대부분의 "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](USAGE.md)를 참고하세요.

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

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

### MCP 클라이언트에 등록하기

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

## 현재 상태

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

## 라이선스

[MIT](LICENSE)