toss-securities-mcp

토스증권 Open API를 감싸는 self-hosted MCP 서버입니다. 본인 API 키로 본인 머신에서 실행하고, Claude Desktop / Claude Code에 연결해 자연어로 계좌·시세를 조회할 수 있습니다.

"삼성전자 몇 주 들고 있어?" · "지난달 체결 내역 보여줘" · "AAPL 지금 얼마야?"

⚠️ 디스클레이머

• 이 프로젝트는 토스증권 공식 제품이 아닌 비공식 커뮤니티 도구입니다.
• 사용 시 토스증권 Open API 약관 준수 책임은 사용자 본인에게 있습니다.
• 시세 정보는 본인 매매 목적으로만 사용 가능합니다 (약관).
• 이 서버는 읽기 전용 조회 도구만 제공합니다. 주문(매수/매도) 기능은 없습니다.
• self-hosted 전용입니다. 타인에게 호스팅 서비스 형태로 제공하지 마세요.

제공 도구

도구	설명
get_account_balance()	계좌 잔고 요약 — 보유 주식 평가(매입/평가/손익) + 현금(KRW/USD 매수 가능 금액)
get_holdings(symbol?)	보유 종목 — 수량, 평단가, 현재가, 평가손익 (종목 필터 가능)
get_transactions(start_date, end_date, symbol?, only_filled?)	기간 내 체결 내역 (커서 페이징 자동 처리)
get_stock_price(symbols)	현재가 조회 (콤마 구분, 최대 200종목)

설치

요구사항: Python 3.12+, uv

git clone <this-repo>
cd toss-securities-mcp
uv sync

설정

1. API 키 발급 — 토스증권 WTS 로그인 → 설정 → Open API 에서 client_id / client_secret 발급
2. 환경변수 작성

cp .env.example .env
# .env 파일에 TOSS_CLIENT_ID, TOSS_CLIENT_SECRET 입력

3. accountSeq 확인 + 스모크 테스트 (실계좌 읽기 전용 조회)

uv run scripts/smoke_test.py

출력된 accountSeq 값을 .env의 TOSS_ACCOUNT_SEQ에 입력하세요.

🔑 .env는 절대 커밋하지 마세요 (.gitignore에 포함되어 있습니다). 키가 노출되면 즉시 토스증권에서 재발급하세요.

Claude Desktop 연결

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "toss-securities": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/toss-securities-mcp", "server.py"],
      "env": {
        "TOSS_CLIENT_ID": "발급받은 client_id",
        "TOSS_CLIENT_SECRET": "발급받은 client_secret",
        "TOSS_ACCOUNT_SEQ": "계좌 accountSeq"
      }
    }
  }
}

Claude Code 연결

claude mcp add toss-securities \
  -e TOSS_CLIENT_ID=... -e TOSS_CLIENT_SECRET=... -e TOSS_ACCOUNT_SEQ=... \
  -- uv run --directory /absolute/path/to/toss-securities-mcp server.py

개발

uv run pytest          # 단위 테스트 (실 API 호출 없음, MockTransport)
uv run mypy            # 타입 체크 (strict)

• API 스펙 정본: https://openapi.tossinvest.com/openapi-docs/latest/openapi.json
• 개발 가이드: CLAUDE.md

로드맵

이 저장소는 더 큰 시스템의 Phase 1입니다:

• Phase 1 (이 저장소): 토스 MCP — 계좌·시세 조회
• Phase 2: portfolio-aggregator-mcp — 멀티 증권사 통합, FIFO 누적 실현손익(Lifetime Realized P/L), 행동 패턴 분석
• Phase 4: NH QV MCP

라이선스

MIT