toss-invest-mcp

토스증권 Open API(guide.json, OpenAPI 3.1)를 기반으로 만든 로컬 stdio MCP 서버입니다. Claude Code / Claude Desktop에 붙여서 시세 조회, 계좌 조회, 주문까지 자연어로 사용할 수 있습니다.

제공 툴 (28개)

그룹	툴
시세	get_prices, get_orderbook, get_trades, get_price_limits, get_candles, get_rankings
종목/시장 정보	get_stocks, get_stock_warnings, get_exchange_rate, get_market_calendar
시장 지표	get_market_indicator_prices, get_market_indicator_candles, get_investor_trading
계좌/자산	get_accounts, get_holdings, get_buying_power, get_sellable_quantity, get_commissions
주문 ⚠️	list_orders, get_order, create_order, modify_order, cancel_order
조건주문 ⚠️	create_conditional_order, list_conditional_orders, get_conditional_order, modify_conditional_order, cancel_conditional_order

⚠️ 주문 관련 툴은 실제 주문이 접수/변경/취소됩니다.

설치 및 빌드

npm install
npm run build

환경변수

변수	필수	설명
TOSS_CLIENT_ID	✅	OAuth2 클라이언트 ID
TOSS_CLIENT_SECRET	✅	OAuth2 클라이언트 시크릿
TOSS_ACCOUNT_SEQ		계좌 툴에서 accountSeq 생략 시 사용할 기본 계좌 (get_accounts로 확인)
TOSS_BASE_URL		API 베이스 URL (기본: https://openapi.tossinvest.com)

액세스 토큰은 서버가 자동으로 발급·캐싱하며, 만료 60초 전 또는 401 응답 시 자동 재발급합니다.

Claude Code 등록

이 저장소의 .mcp.json이 프로젝트 스코프로 서버를 등록합니다. 셸 환경에 TOSS_CLIENT_ID / TOSS_CLIENT_SECRET를 export한 뒤 이 디렉터리에서 claude를 실행하면 됩니다.

다른 프로젝트에서도 쓰려면 user 스코프로 등록:

claude mcp add toss-invest --scope user \
  -e TOSS_CLIENT_ID=발급받은_ID \
  -e TOSS_CLIENT_SECRET=발급받은_시크릿 \
  -- node /Users/doogi/toss-mcp/dist/index.js

Claude Desktop 등록

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "toss-invest": {
      "command": "node",
      "args": ["/Users/doogi/toss-mcp/dist/index.js"],
      "env": {
        "TOSS_CLIENT_ID": "발급받은_ID",
        "TOSS_CLIENT_SECRET": "발급받은_시크릿"
      }
    }
  }
}

사용 예시

• "삼성전자 현재가 알려줘" → get_prices(symbols=["005930"])
• "코스피 거래대금 상위 10개" → get_rankings(type=MARKET_TRADING_AMOUNT, marketCountry=KR, duration=realtime, count=10)
• "내 보유 종목 보여줘" → get_accounts → get_holdings
• "삼성전자 10주 70,000원 지정가 매수" → create_order(...) ⚠️