scjang01/tossinvest-mcp

프로그램 개요
tossinvest-mcp는 토스증권 Open API(현재가 조회, 주문, 잔고 조회 등)를 OpenAI 서비스, Claude Desktop, Cursor 같은 MCP 지원 앱에서 사용할 수 있게 해주는 로컬 MCP 서버입니다.
쉽게 말해, 이 프로그램을 MCP 클라이언트에 등록하면 AI에게 다음처럼 요청할 수 있습니다.
이 프로그램은 사용자의 컴퓨터에서만 실행됩니다.
가장 중요한 주의사항
토스증권 Open API에는 샌드박스나 모의투자 환경이 없습니다.
거래 기능을 켜면 실제 계좌에 실제 주문을 생성, 정정, 취소할 수 있습니다. 처음 사용할 때는 반드시 거래 기능을 켜지 말고 조회 기능부터 확인하세요.
기본 설정에서는 주문 생성, 정정, 취소 도구가 등록되지 않습니다.
프로그램으로 할 수 있는 기능 및 특징
거래 기능을 켜지 않아도 아래 기능을 사용할 수 있습니다.
- 국내/미국 주식 현재가 조회
- 호가 조회
- 최근 체결 내역 조회
- 캔들 차트 조회
- 상한가/하한가 조회
- 종목 기본 정보 조회
- 매수 유의사항 조회
- 환율 조회
- 국내/미국 장 운영 시간 조회
- 계좌 목록 조회
- 보유 주식 조회
- 매수 가능 금액 조회
- 판매 가능 수량 조회
- 매매 수수료 조회
- 주문 목록 조회
- 주문 상세 조회
거래 기능을 켠 경우 사용할 수 있는 도구:
- toss_create_order: 주문 생성
- toss_modify_order: 주문 정정
- toss_cancel_order: 주문 취소
특징:
- npx tossinvest-mcp로 실행되므로 별도 프로그램 설치 과정이 짧습니다.
- API Key와 Secret Key는 환경변수로 전달합니다.
- OAuth 토큰은 내부에서 자동 발급하고, 만료 60초 전에 자동 갱신합니다.
- 계좌가 필요한 기능은 기본적으로 accountSeq 1번 계좌를 사용합니다.
- 계좌가 여러 개이거나 다른 계좌를 쓰고 싶으면 TOSSINVEST_ACCOUNT 값으로 변경할 수 있습니다.
- 주문 생성, 정정, 취소 기능은 기본적으로 꺼져 있습니다.
- 주문 기능을 켜도 기본값에서는 confirmOrderAction: true 확인값이 없으면 주문 API를 호출하지 않습니다.
- 주문 한도, 매도/시장가 차단, 종목 허용목록, 일일 한도 같은 가드레일을 환경변수로 켤 수 있고, 모든 검사는 토스증권 주문 API 호출 전에 서버에서 강제됩니다. (아래 거래 가드레일 참고)
중요: toss_modify_order는 기존 주문을 그 자리에서 수정하는 단순 PATCH가 아닙니다. 토스증권 API는 원주문을 대체하는 방식으로 처리하며, 정정 후 새 orderId를 반환합니다. 이후 주문 상세 조회, 재정정, 취소에는 새로 받은 orderId를 사용하세요.
설치방법
아래 순서대로 진행하면 됩니다.
1. Node.js 설치 확인
터미널 또는 PowerShell을 열고 아래 명령어를 입력합니다.
v20 이상이 나오면 다음 단계로 넘어가면 됩니다.
Node.js가 없거나 버전이 낮다면 https://nodejs.org 에서 LTS 버전을 설치한 뒤 터미널을 새로 열어 다시 확인하세요.
2. 토스증권 Open API Key 준비
토스증권 WTS에 로그인한 뒤 Open API 설정 화면으로 이동합니다.
그 화면에서 아래 값을 발급받아 둡니다.
- API Key
- Secret Key
이 두 값은 MCP 설정에 넣어야 합니다. 다른 사람에게 공유하지 마세요.
3. 허용 IP 등록
토스증권 Open API는 허용된 IP에서만 호출할 수 있습니다. 이 설정이 빠져 있으면 허용되지 않은 IP 주소입니다. 같은 오류가 발생합니다.
먼저 현재 컴퓨터의 공인 IP를 확인합니다. 아래 명령어를 사용하세요.
PowerShell (Windows):
macOS 또는 Linux 터미널:
나온 IP 주소를 토스증권 WTS의 Open API 설정 화면에서 허용 IP 목록에 추가합니다.
대략적인 흐름:
1. 토스증권 WTS에 로그인합니다.
2. 설정 - Open API 메뉴로 이동합니다.
3. 허용 IP 관리 영역을 찾습니다.
4. 위에서 확인한 공인 IP를 추가합니다.
4. MCP 클라이언트에 등록
MCP 클라이언트의 설정 파일 또는 MCP Servers 설정 화면에 아래 내용을 추가합니다.
설정 후 MCP 클라이언트를 완전히 종료했다가 다시 실행하세요.
처음 실행할 때 npm이 tossinvest-mcp 패키지를 자동으로 내려받습니다.
5. 계좌번호 확인
처음에는 TOSSINVEST_ACCOUNT를 넣지 않아도 됩니다. 이 프로그램은 기본값으로 accountSeq 1번 계좌를 사용합니다.
다만 계좌가 여러 개이거나 1번 계좌가 맞는지 확인하고 싶다면 계좌 목록을 조회하세요.
MCP 클라이언트에서 다음처럼 요청합니다.
응답에서 accountSeq 값을 찾습니다. 다른 계좌를 기본 계좌로 쓰고 싶다면 설정에 아래 값을 추가하거나 바꾸면 됩니다.
예를 들어 accountSeq가 2인 계좌를 쓰고 싶다면 이렇게 설정합니다.
계좌번호를 명시한 전체 예시는 다음과 같습니다.
TOSSINVEST_ACCOUNT를 설정하지 않으면 기본값 1을 사용합니다. 설정하면 보유 주식, 주문 목록, 매수 가능 금액처럼 계좌가 필요한 기능에서 해당 계좌를 기본으로 사용합니다.
6. 조회 기능 테스트
MCP 클라이언트에서 아래처럼 요청해 봅니다.
거래 기능 켜기
다시 한 번 확인하세요. 토스증권 Open API에는 샌드박스가 없습니다. 거래 기능을 켜면 실제 주문이 나갈 수 있습니다.
거래 기능을 사용하려면 MCP 설정의 env에 아래 값을 추가합니다.
전체 예시:
거래 기능을 켜도 주문 도구는 추가 확인값이 없으면 실행되지 않습니다. 주문 생성, 정정, 취소 도구는 요청 입력에 confirmOrderAction: true가 있어야 토스증권 API를 호출합니다.
confirmOrderAction을 true로 넣는 방법
confirmOrderAction은 MCP 설정에 넣는 환경변수가 아닙니다. 주문 생성, 정정, 취소 도구를 호출할 때마다 들어가는 주문 요청 입력값입니다.
예를 들어 주문 생성 도구의 실제 입력은 이런 형태입니다.
MCP 클라이언트에서 자연어로 요청할 때는 아래처럼 명확히 말하는 것이 좋습니다.
정정이나 취소도 마찬가지입니다.
클라이언트에 따라 주문 도구 실행 전에 승인 버튼이나 확인 창을 보여줄 수 있습니다. 그 경우에도 confirmOrderAction: true가 주문 tool 입력에 포함되어야 합니다.
확인값 없이 주문 실행하기 (자동화)
> 참고: 이전 버전의 TOSSINVEST_YOLO_TRADING 옵션은 제거되었습니다. 확인값을 끄더라도 나머지 가드레일은 그대로 적용됩니다.
자동화 환경처럼 매번 confirmOrderAction: true를 넣기 어렵다면 확인 요구만 끌 수 있습니다.
이 값을 끄면 confirmOrderAction 없이도 주문을 보낼 수 있지만, 주문 한도·매도/시장가 차단·종목 허용목록·일일 한도 등 켜져 있는 다른 가드레일은 계속 적용됩니다. 확인값을 끄기 전에 금액/일일 한도를 함께 설정해 두는 것을 강력히 권장합니다.
거래 가드레일
가드레일은 "AI가 실수로, 또는 너무 크게/너무 자주 주문을 넣는 것"을 막아 주는 안전장치입니다. 모든 검사는 주문이 토스증권 서버에 도달하기 **전에** 이 프로그램 안에서 이루어지므로, 한도를 넘는 주문은 애초에 토스로 전송되지 않습니다.
모든 옵션은 MCP 설정의 env에 한 줄씩 추가해 켜며, 켜지 않은 옵션은 적용되지 않습니다(기본값은 보수적입니다). 값은 모두 문자열로 적습니다. 예: "TOSSINVEST_MAX_ORDER_AMOUNT_KRW": "500000".
한눈에 보기 (요약 표)
| 이름 | 기본값 | 한 줄 설명 |
| --- | --- | --- |
| TOSSINVEST_REQUIRE_ORDER_CONFIRMATION | true | 주문마다 confirmOrderAction: true 확인값을 요구 |
| TOSSINVEST_MAX_ORDER_AMOUNT_KRW | 없음 | 1회 주문 금액 상한(원) |
| TOSSINVEST_MAX_ORDER_AMOUNT_USD | 없음 | 1회 주문 금액 상한(달러) |
| TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW | 없음 | 하루 누적 주문 금액 상한(원) |