toss-invest-mcp

토스증권 Open API를 Claude · Cursor 같은 AI 클라이언트에서 쓸 수 있게 해주는 비공식 MCP 서버입니다. 시세·차트·기술지표·잔고 조회는 자유롭게, 주문은 여러 겹의 안전장치를 거쳐서만 나갑니다.

English

⚠️ 토스증권과 무관한 개인 프로젝트입니다. 실제 돈이 오가는 도구이니 기본값(모의 주문)으로 충분히 써본 뒤에 live 로 바꾸세요. 이 소프트웨어 사용으로 생긴 손실에 대해 작성자는 책임지지 않습니다 (MIT 라이선스).

할 수 있는 것

나: SOXL 지금 RSI 어때? 과매도면 10주 LOC 매수 미리보기 만들어줘
AI: (technicals → preview_order) RSI 27.4로 과매도 구간이에요.
    [실주문] SOXL LOC(장마감 지정가) 매수 10주 @ 24.50 · 예상 금액 약 $245.00
    ⚠️ 레버리지/인버스 상품 (배수 3) ...
    실행할까요?

국내(6자리 코드)와 미국(티커) 주식 모두 지원합니다. 지정가, 시장가, LOC(장마감 지정가), 미국 금액 주문과 소수점 매도도 됩니다.

Related MCP server: io.github.kcw2034/toss-invest-mcp

주문 안전장치

AI가 실수하거나 프롬프트 인젝션에 당해도 사고가 커지지 않도록 설계했습니다.

1. 2단계 주문: preview_order 로 한도·잔고·매도가능수량을 검사한 미리보기를 먼저 만들고, 사용자가 확인한 뒤에만 place_order(preview_id) 를 호출합니다. 미리보기는 5분 뒤 만료되고 한 번만 실행됩니다. 확인코드를 5번 틀리면 미리보기가 폐기됩니다.

2. 모드: off(주문 툴 차단) / dry_run(기본값, 모의 체결) / live(실주문).

3. 매수 한도 (선택): 기본은 무제한이고, 사람이 환경변수로 직접 설정합니다. 1회·일일 금액 한도(USD/KRW 각각)와 일일 매수 건수 한도를 걸 수 있고, 시장가는 현재가에 3% 버퍼를 얹어 보수적으로 계산합니다. 매도는 손절이 막히지 않도록 한도 대상이 아닙니다 (매도가능수량 검사는 그대로). AI는 한도를 바꿀 수 없습니다.

4. 허용 종목: ALLOWED_SYMBOLS=AAPL,TSLA 처럼 지정하면 다른 종목은 주문할 수 없습니다.

5. 킬스위치: toss-invest-mcp kill on 을 실행하면 재시작 없이 즉시 새 주문이 막힙니다. 취소는 계속 됩니다.

6. 폰 확인코드 (선택): NTFY_TOPIC 을 설정하면 6자리 코드가 ntfy 앱으로만 전송됩니다. AI는 코드를 볼 수 없어서 사람이 직접 입력해야만 주문이 나갑니다.

7. 멱등키: preview_id 를 clientOrderId 로 보내므로 네트워크 오류로 재시도해도 주문은 한 번만 접수됩니다.

8. 레버리지/인버스 경고와 현재가에서 멀리 떨어진 지정가 경고를 표시합니다.

9. 모든 미리보기·실행·거절 내역을 orders.log.jsonl 에 기록합니다.

준비

1. 토스증권 Open API에서 API 키(Client ID / Secret)를 발급받습니다.

2. WTS > 설정 > Open API > 허용 IP 에 이 서버를 실행할 컴퓨터의 공인 IP를 등록합니다. (curl ifconfig.me)

3. Python 3.10 이상과 uv를 설치합니다 (pip도 됩니다).

토스는 Client 하나당 유효 토큰이 1개뿐입니다. 이 서버는 토큰을 DATA_DIR/token.json 에 캐시해서 공유하니, 같은 키로 다른 스크립트를 함께 돌리면 토큰이 서로를 무효화할 수 있습니다.

설치 & 연결

Claude Desktop / Cursor / 그 밖의 stdio 클라이언트

{
  "mcpServers": {
    "toss-invest": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jihwan0102/toss-invest-mcp", "toss-invest-mcp"],
      "env": {
        "TOSS_CLIENT_ID": "...",
        "TOSS_CLIENT_SECRET": "...",
        "TRADING_MODE": "dry_run"
      }
    }
  }
}

Claude Code

claude mcp add toss-invest \
  -e TOSS_CLIENT_ID=... -e TOSS_CLIENT_SECRET=... -e TRADING_MODE=dry_run \
  -- uvx --from git+https://github.com/jihwan0102/toss-invest-mcp toss-invest-mcp

claude.ai 커스텀 커넥터 (원격 HTTP)

허용 IP가 고정된 서버(VPS 등)에서 실행합니다.

uv tool install git+https://github.com/jihwan0102/toss-invest-mcp
cp .env.example toss.env && chmod 600 toss.env      # 값 채우기
echo "MCP_PATH_SECRET=$(toss-invest-mcp gen-secret)" >> toss.env
toss-invest-mcp --env-file toss.env serve --http     # 127.0.0.1:8000

그다음 HTTPS 리버스 프록시(nginx, Caddy)를 앞에 두고 claude.ai > 설정 > 커넥터에 https://<도메인>/<MCP_PATH_SECRET>/mcp 를 등록합니다. 이 URL은 비밀번호나 마찬가지입니다. 헤더를 지원하는 클라이언트라면 MCP_AUTH_TOKEN 으로 Bearer 인증도 쓸 수 있습니다. systemd 유닛과 nginx 예시는 deploy/에 있습니다.

관리 명령

toss-invest-mcp check          # 키와 허용 IP 확인 (조회만 함)
toss-invest-mcp status         # 모드, 매수 한도, 오늘 사용량
toss-invest-mcp kill on|off    # 킬스위치
toss-invest-mcp logs -n 50     # 주문 로그
toss-invest-mcp gen-secret     # 비밀값 생성

모든 명령에 --env-file <파일> 을 줄 수 있습니다.

설정 (환경변수)

개발

uv venv && uv pip install -e '.[dev]'
.venv/bin/pytest && .venv/bin/ruff check .

테스트는 토스 API를 httpx.MockTransport 로 흉내 내므로 키 없이 돌아갑니다.

라이선스

MIT