토스증권 MCP 서버 (tossinvest-mcp)

English

Claude에서 토스증권 계좌로 국내·미국 주식을 조회하고 주문할 수 있게 해주는 Model Context Protocol (MCP) 서버입니다. 토스증권 Open API를 사용해 주식 시세·호가· 체결·차트·투자자 수급·보유 종목·주문 가능 금액·환율을 조회하고, 사용자 확인 절차를 거쳐 일반 주문과 SINGLE·OCO·OTO 조건주문을 등록합니다. Claude Code, Claude Desktop 등 MCP를 지원하는 AI 클라이언트에서 바로 사용할 수 있습니다.

toss client key 생성 : https://corp.tossinvest.com/ko/open-api

Claude Code에서 사용하기

이 패키지가 npm에 배포된 뒤에는 저장소를 clone할 필요가 없습니다. Claude Code를 사용할 프로젝트의 .mcp.json에 아래 내용을 추가하세요.

config.json

{
  "mcpServers": {
    "toss": {
      "command": "npx",
      "args": ["-y", "@soehd0889/tossinvest-mcp"],
      "env": {
        "TOSS_CLIENT_ID": "토스_클라이언트_ID",
        "TOSS_CLIENT_SECRET": "토스_클라이언트_시크릿"
      }
    }
  }
}

토스증권 Open API 개발자 콘솔에서 TOSS_CLIENT_ID와 TOSS_CLIENT_SECRET을 발급받아 입력한 뒤 Claude Code를 재시작하세요. 자격 증명은 Git에 커밋하거나 프롬프트에 공유하면 안 됩니다.

npx는 첫 실행 때 패키지를 내려받고 이후에는 캐시를 사용합니다. Node.js 18 이상이 필요합니다.

제공 도구

도구	설명
`toss_get_price`	한국·미국 주식의 현재가 조회
`toss_resolve_symbol`	회사 이름을 티커 또는 국내 종목 코드로 변환
`toss_get_holdings`	보유 종목과 손익 조회
`toss_get_buying_power`	원화 또는 달러 주문 가능 금액 조회
`toss_get_exchange_rate`	환율 조회 (기본: USD → KRW)
`toss_get_candles`	1분봉 또는 일봉 OHLCV 조회
`toss_get_orderbook` / `toss_get_recent_trades`	실시간 호가와 최근 체결 조회
`toss_get_market_calendar`	한국·미국 장 운영 시간 및 휴장일 조회
`toss_get_stock_warnings`	투자 유의사항·거래 경고 조회
`toss_get_stock_investor_trading` / `toss_get_short_selling`	국내 종목 투자자 수급·공매도 동향 조회
`toss_get_rankings`	거래대금·거래량·상승·하락 종목 랭킹 조회
`toss_get_market_indicator_prices` / `toss_get_market_indicator_candles`	지수·시장 지표의 현재가와 캔들 조회
`toss_get_market_investor_trading`	코스피·코스닥 투자자별 매매대금 조회
`toss_prepare_order`	주식 주문을 검증·미리보기만 함 (실주문 없음)
`toss_prepare_conditional_order`	SINGLE·OCO·OTO 조건주문을 검증·미리보기
`toss_submit_prepared_order`	사용자 확인을 거친 일회용 주문을 제출

주문 안전 절차

주문은 항상 2단계로 진행됩니다. toss_prepare_order 또는 toss_prepare_conditional_order는 주문을 실행하지 않고 미리보기만 만듭니다. AI는 내용을 사용자에게 보여주고 명시적인 확인을 받은 후에만 toss_submit_prepared_order를 호출해야 합니다. 확인 토큰은 정확히 그 주문에만 연결되며 60초 후 만료되고, 한 번 사용하거나 서버를 재시작하면 무효화됩니다. 이는 착오주문 위험을 낮추는 장치이며 사용자의 최종 검토를 대체하지 않습니다.

로컬 개발

bash

git clone https://github.com/Jeric1223/tossinvest-mcp.git
cd tossinvest-mcp
npm install
npm test

로컬에서 실행할 때는 .env.example을 복사해 자격 증명을 입력합니다.

bash

cp .env.example .env

참고 사항

처음 실행하면 KOSPI, KOSDAQ, NASDAQ, NYSE, AMEX의 종목 마스터를 다운로드하며, 이후에는 캐시를 사용하고 하루에 한 번 백그라운드 갱신합니다.
API의 숫자 필드는 문자열로 오며, 등락률은 소수 형식입니다. 예: -0.3799는 -37.99%입니다.
API 제한은 시세 초당 15회, 자산 초당 5회, 계좌 초당 1회입니다.

면책 사항

이 프로젝트는 토스증권과 무관한 비공식 도구이며 투자 조언을 제공하지 않습니다. 사용에 따른 책임은 사용자에게 있습니다.

라이선스

MIT