mcp-toss

토스증권 Open API를 위한 MCP(Model Context Protocol) 서버. 시세·종목·시장정보·계좌·보유주식 조회와 주문(2단계 확인) 기능을 도구로 제공합니다.

• Base API: https://openapi.tossinvest.com
• 인증: OAuth 2.0 Client Credentials (client_id + client_secret → access token)
• 전송: stdio (Claude Desktop / Claude Code 등 로컬 MCP 클라이언트)

설치 / 설정

자격증명은 코드에 두지 않습니다. 사용자마다 본인 자격증명을 MCP 클라이언트 설정의 env에 넣으세요.

{
  "mcpServers": {
    "toss": {
      "command": "npx",
      "args": ["-y", "mcp-toss"],
      "env": {
        "TOSS_CLIENT_ID": "your_client_id",
        "TOSS_CLIENT_SECRET": "your_client_secret",
        "TOSS_ACCOUNT_NO": "your_account_seq (선택)"
      }
    }
  }
}

| 환경변수 | 필수 | 설명 | |---|---|---| | TOSS_CLIENT_ID | ✅ | OAuth2 client id | | TOSS_CLIENT_SECRET | ✅ | OAuth2 client secret | | TOSS_ACCOUNT_NO | ⬜ | 기본 계좌 시퀀스(정수). 미지정 시 도구의 account 인자로 전달 | | TOSS_BASE_URL | ⬜ | 기본 https://openapi.tossinvest.com override용 |

도구

조회 (read-only)

| 도구 | 설명 | |---|---| | get_orderbook | 호가 조회 | | get_prices | 현재가 조회 (여러 종목 쉼표 구분) | | get_trades | 최근 체결 내역 | | get_price_limits | 상/하한가 | | get_candles | 캔들 차트 (interval: 1m/1d) | | search_stocks | 종목 기본 정보 | | get_stock_warnings | 매수 유의사항 | | get_exchange_rate | 환율 (KRW/USD) | | get_market_calendar_kr | 국내(KRX) 장 운영 정보 | | get_market_calendar_us | 미국 장 운영 정보 | | list_accounts | 계좌 목록 (계좌 시퀀스 확인용) | | get_holdings | 보유 주식 | | list_orders | 주문 목록 (status: OPEN/CLOSED) | | get_order | 주문 상세 | | get_buying_power | 매수 가능 금액 | | get_sellable_quantity | 판매 가능 수량 | | get_commissions | 매매 수수료 |

주문 (2단계 확인)

| 미리보기 | 확정 | |---|---| | preview_order | place_order | | preview_order_modify | modify_order | | preview_order_cancel | cancel_order |

주문 안전장치

주문은 항상 2단계로 동작합니다.

1. preview_* 도구가 주문 내용을 요약하고 confirmToken을 발급합니다. (이 단계에서는 실제 주문이 나가지 않습니다.)
2. 동일한 주문 파라미터 + 그 confirmToken으로 확정 도구(place_order 등)를 호출해야 실제로 주문이 전송됩니다.

confirmToken은 60초간 1회만 유효하며, preview 때와 파라미터가 다르면 거부됩니다. 이로써 착오 주문과 의도치 않은 실주문을 막습니다.

⚠️ 주문 도구는 실제 매매를 발생시킵니다. 본인 계좌와 자격증명으로만 사용하세요.

개발

npm install
npm test          # vitest
npm run build     # tsc → dist/
npm run dev       # tsx src/index.ts

라이선스

MIT