tossinvest-mcp
A local read-only MCP server for querying Toss Securities market data, sector data, account information, and order history.
Retrieve stock prices, orderbooks, recent trades, price limits, candles, stock master data, and buy warnings for KRX/US symbols.
List stocks by exchange and filter by status, security type, common shares, or symbols only.
Query KR stock investor trading, program trading, short selling, credit trading, and securities lending trends.
Get KR/US stock rankings and KR investor net-buy/net-sell rankings.
Query Korean market indicators: index/bond prices, candles, and investor trading amounts.
Browse sectors, sector details, rankings, constituent stocks, and related ETFs.
Get exchange rates and Korean/US market calendars.
List accounts and query holdings, transactions, buying power, sellable quantity, and commissions.
List or retrieve regular orders and conditional orders.
No trading/order creation, modification, or cancellation tools are present in this schema.
Enables OpenAI services to access Toss Securities Open API for stock price inquiries, order execution, and portfolio management.
tossinvest-mcp
프로그램 개요
현재 버전: 0.3.2
tossinvest-mcp는 토스증권 Open API(현재가 조회, 주문, 잔고 조회 등)를 OpenAI 서비스, Claude Desktop, Cursor 같은 MCP 지원 프로그램에서 사용할 수 있게 해주는 로컬 MCP 서버입니다.
쉽게 말해, 이 프로그램을 MCP 클라이언트에 등록하면 AI에게 다음처럼 요청할 수 있습니다.
삼성전자 현재가를 조회해줘.내 토스증권 보유 주식을 보여줘.삼성전자 1주를 주문해줘.이 프로그램은 사용자의 컴퓨터에서만 실행됩니다.
Related MCP server: tossinvest-openapi-mcp
가장 중요한 주의사항
토스증권 Open API에는 샌드박스나 모의투자 환경이 없습니다.
거래 기능을 켜면 실제 계좌에 실제 주문을 생성, 정정, 취소할 수 있습니다. 처음 사용할 때는 반드시 거래 기능을 켜지 말고 조회 기능부터 확인하세요.
기본 설정에서는 주문 생성, 정정, 취소 도구가 등록되지 않습니다.
프로그램으로 할 수 있는 기능 및 특징
거래 기능을 켜지 않아도 아래 기능을 사용할 수 있습니다.
도구명 | 기능 |
| 국내·미국 주식 현재가 조회 |
| 매수·매도 호가 조회 |
| 종목의 최근 체결 내역 조회 |
| 종목의 분봉·일봉 차트 조회 |
| 종목의 상한가·하한가 조회 |
| 종목명·시장·통화 등 기본 정보 조회 |
| 거래소별 전체 종목 목록 조회. 심볼만 필요하면 |
| 종목의 매수 유의사항 조회 |
| 국내 종목의 투자자별 매매동향 조회 |
| 국내 종목의 프로그램매매 동향 조회 |
| 국내 종목의 공매도 동향 조회 |
| 국내 종목의 신용거래 동향 조회 |
| 국내 종목의 대차거래 동향 조회 |
| 국내·미국 주식의 거래대금·거래량·등락률 등 랭킹 조회 |
| 국내 종목의 외국인·기관·개인 순매수·순매도 랭킹 조회 |
| 국내 지수·국채 등 시장 지표의 현재가 조회 |
| 시장 지표의 캔들 차트 조회 |
| 코스피·코스닥 시장의 투자자별 매매대금 조회 |
| 섹터 목록 조회 |
| 섹터 상세 정보 조회 |
| 섹터별 등락률·거래대금 랭킹 조회 |
| 섹터에 포함된 주식 조회 |
| 섹터 관련 ETF 조회 |
| 원화·달러 환율 조회 |
| 국내 주식시장 운영일·시간 조회 |
| 미국 주식시장 운영일·시간 조회 |
| 사용 가능한 계좌 목록 조회 |
| 계좌의 보유 주식 조회 |
| 계좌의 매매·입출금·환전·배당 등 거래내역 조회 |
| 계좌의 매수 가능 금액 조회 |
| 종목의 매도 가능 수량 조회 |
| 계좌의 매매 수수료 조회 |
| 일반 주문 목록 조회 |
| 일반 주문 상세 조회 |
| 조건주문 목록 조회 |
| 조건주문 상세 조회 |
거래 기능을 켠 경우 사용할 수 있는 도구:
도구명 | 기능 |
| 일반 주문 생성 |
| 일반 주문 정정 |
| 일반 주문 취소 |
| 조건주문 생성 |
| 조건주문 수정 |
| 조건주문 취소 |
0.3.1 이상 버전은 투자자별 순매수·순매도 랭킹과 계좌 거래내역 조회를 추가해 조회 36개·거래 6개를 제공합니다. 로컬 stdio 방식이며 WebSocket이나 원격 HTTP/SSE 서버는 제공하지 않습니다.
설치방법
아래 순서대로 진행하면 됩니다.
1. Node.js 설치 확인
터미널 또는 PowerShell을 열고 아래 명령어를 입력합니다.
node -vv20 이상이 나오면 다음 단계로 넘어가면 됩니다.
Node.js가 없거나 버전이 낮다면 Node.js 공식 사이트에서 LTS 버전을 설치한 뒤 터미널을 새로 열어 다시 확인하세요.
2. 토스증권 Open API 연결 정보 준비
토스증권 WTS에 로그인한 뒤 Open API 설정 화면으로 이동합니다.
그 화면에서 아래 값을 발급받아 둡니다.
Client IDClient Secret
이 두 값은 MCP 설정에 넣어야 합니다. 다른 사람에게 공유하지 마세요.
3. 허용 IP 등록
토스증권 Open API는 허용된 IP에서만 호출할 수 있습니다. 이 설정이 빠져 있으면 허용되지 않은 IP 주소입니다. 같은 오류가 발생합니다.
먼저 현재 컴퓨터의 공인 IP를 확인합니다. 아래 명령어를 사용하세요.
PowerShell (Windows):
(Invoke-WebRequest -UseBasicParsing https://api.ipify.org).ContentmacOS 또는 Linux 터미널:
curl https://api.ipify.org나온 IP 주소를 토스증권 WTS의 Open API 설정 화면에서 허용 IP 목록에 추가합니다.
대략적인 흐름:
토스증권 WTS에 로그인합니다.
설정 - Open API 메뉴로 이동합니다.
허용 IP 관리 영역을 찾습니다.
위에서 확인한 공인 IP를 추가합니다.
4. MCP 클라이언트에 등록
MCP 클라이언트의 설정 파일 또는 MCP Servers 설정 화면에 아래 내용을 추가합니다.
{
"mcpServers": {
"tossinvest": {
"command": "npx",
"args": ["-y", "tossinvest-mcp"],
"env": {
"TOSSINVEST_CLIENT_ID": "발급받은-Client-ID",
"TOSSINVEST_CLIENT_SECRET": "발급받은-Client-Secret"
}
}
}
}설정 후 MCP 클라이언트를 완전히 종료했다가 다시 실행하세요.
처음 실행할 때 npm이 지정한 버전의 tossinvest-mcp 패키지를 내려받습니다.
env 안에 연결 정보를 넣으면 별도 .env 파일은 필요하지 않습니다. 서버가 .env 파일을 자동으로 읽지는 않습니다. 다른 MCP가 이미 등록되어 있다면 기존 설정을 덮어쓰지 말고 mcpServers 안에 tossinvest 항목만 추가하세요.
5. 계좌 확인
처음에는 TOSSINVEST_ACCOUNT를 넣지 않아도 됩니다. 시세 조회에는 계좌가 필요하지 않습니다. 보유 주식이나 주문처럼 계좌가 필요한 기능에서는 AI가 계좌 목록을 확인한 뒤 accountSeq를 입력합니다.
MCP 클라이언트에서 다음처럼 요청합니다.
토스증권 계좌 목록을 조회해줘.응답의 accountSeq는 실제 계좌번호가 아니라 API에서 사용하는 계좌 순번입니다. 계좌가 하나면 AI가 선택할 수 있고, 여러 개여서 원하는 계좌를 구분하기 어려우면 사용자에게 확인하도록 도구에 안내되어 있습니다.
특정 계좌만 사용하려면 확인한 accountSeq를 TOSSINVEST_ACCOUNT에 넣습니다. 예를 들어 순번이 2인 계좌를 고정하려면 다음처럼 설정합니다.
{
"mcpServers": {
"tossinvest": {
"command": "npx",
"args": ["-y", "tossinvest-mcp"],
"env": {
"TOSSINVEST_CLIENT_ID": "발급받은-Client-ID",
"TOSSINVEST_CLIENT_SECRET": "발급받은-Client-Secret",
"TOSSINVEST_ACCOUNT": "2"
}
}
}
}설정하면 계좌 관련 기능을 해당 계좌로 고정하며, 다른 accountSeq를 지정한 호출은 거절합니다. 미설정 시 기본 계좌는 없고, 계좌 관련 도구마다 accountSeq가 필요합니다.
6. 조회 기능 테스트
MCP 클라이언트에서 아래처럼 요청해 봅니다.
삼성전자 현재가를 조회해줘.내 토스증권 보유 주식을 보여줘.AAPL 최근 체결 내역 10개를 조회해줘.대기 중인 주문 목록을 보여줘.거래 기능 켜기
다시 한 번 확인하세요. 토스증권 Open API에는 샌드박스가 없습니다. 거래 기능을 켜면 실제 주문이 나갈 수 있습니다.
거래 기능을 사용하려면 MCP 설정의 env에 아래 값을 추가합니다.
"TOSSINVEST_ENABLE_TRADING": "true"전체 예시:
{
"mcpServers": {
"tossinvest": {
"command": "npx",
"args": ["-y", "tossinvest-mcp"],
"env": {
"TOSSINVEST_CLIENT_ID": "발급받은-Client-ID",
"TOSSINVEST_CLIENT_SECRET": "발급받은-Client-Secret",
"TOSSINVEST_ACCOUNT": "2",
"TOSSINVEST_ENABLE_TRADING": "true"
}
}
}
}TOSSINVEST_ACCOUNT의 2는 예시입니다. 계좌 목록에서 확인한 순번으로 바꾸세요. 설정 후 MCP 클라이언트를 완전히 종료했다가 다시 실행합니다.
0.3.0 버전 이상에서는 confirmOrderAction 확인값 없이 일반 주문과 조건주문을 생성·정정·취소할 수 있습니다. 매도와 시장가도 거래 기능을 켜면 사용할 수 있습니다. 금액·건수 한도가 필요하다면 아래 설정을 함께 넣으세요.
MCP 클라이언트에서 자연어로 요청할 때는 아래처럼 구체적으로 말하는 것이 좋습니다.
토스증권에서 선택한 계좌로 삼성전자 1주를 70000원 지정가로 매수 주문해줘.이 주문을 71000원으로 정정해줘. 정정 후 새 주문 ID도 알려줘.이 주문을 취소해줘. 취소가 확인됐는지도 조회해줘.고액 주문 확인: confirmHighValueOrder
confirmHighValueOrder는 환경변수가 아니라 주문 입력값입니다. 토스가 고액 주문 확인을 요구하면 사용자가 금액을 확인하고 승인한 경우에만 true로 전달해야 합니다. AI가 오류를 우회하려고 자동으로 true로 바꾸면 안 됩니다.
이 프로그램은 고액 여부를 별도로 판정하지 않고 토스의 오류 코드·안내를 전달합니다. 아래의 시장가 버퍼는 MCP의 주문 예산용이며 토스의 고액 주문 판정 기준과는 다릅니다.
거래 가드레일
가드레일은 "AI가 실수로, 또는 너무 크게/너무 자주 주문을 넣는 것"을 줄이기 위한 안전장치입니다. 설정한 한도는 주문 API를 호출하기 전에 검사합니다. 실제 체결금액·수수료·세금·손익을 관리하는 기능은 아닙니다.
옵션은 MCP 설정의 env에 추가합니다. 금액·건수 한도와 종목 허용목록은 기본값이 없으며, 설정한 항목만 적용됩니다. 값은 모두 문자열로 적습니다. 예: "TOSSINVEST_MAX_ORDER_AMOUNT_KRW": "500000".
한눈에 보기 (요약 표)
이름 | 기본값 | 한 줄 설명 |
| 없음 | 1회 주문 금액 상한(원) |
| 없음 | 1회 주문 금액 상한(달러) |
| 없음 | 국내 일일 주문 금액 상한(원) |
| 없음 | 미국 일일 주문 금액 상한(달러) |
| 없음 | 국내 일일 생성·정정 성공 건수 상한 |
| 없음 | 미국 일일 생성·정정 성공 건수 상한 |
| 없음 | 거래 가능 종목만 지정 |
|
| 수량 시장가 주문의 예산 계산 버퍼(%) |
| OS 데이터 폴더 | 토큰과 일일 집계를 공유할 디렉터리 |
| 자동 지정 | 기존 상태 파일 경로 및 새 상태 파일명 접두사 |
옵션별 상세 설명
TOSSINVEST_MAX_ORDER_AMOUNT_KRW / TOSSINVEST_MAX_ORDER_AMOUNT_USD (기본: 없음)
주문 한 건의 금액 상한입니다. KRW는 원화, USD는 달러 기준이며 원↔달러 환산은 하지 않습니다. 예를 들어 KRW에 "500000"을 설정하면 50만 원 초과 주문을 차단합니다. 양수인 금액을 넣고, 소수점도 사용할 수 있습니다.
TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW / TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD (기본: 없음)
이 MCP로 접수한 주문 예산의 일일 상한입니다. 같은 범위의 매수·매도를 합산하며, 국내·미국 금액은 따로 계산합니다. 예를 들어 20달러 매수 후 20달러 매도 주문을 하면 사용액은 40달러입니다.
시장 | 금액·건수 초기화 시각 |
국내(KRW) | 매일 KST 20:01 |
미국(USD) | 매일 KST 10:01 |
자정에는 초기화하지 않습니다. 한국 시간 고정이며 서머타임·휴장일에 따라 자동 변경하지 않습니다. 예를 들어 월요일 밤의 미국 주문과 화요일 오전 10:00의 미국 주문은 같은 구간이고, 화요일 10:01부터 새 한도를 사용합니다.
TOSSINVEST_DAILY_MAX_ORDER_COUNT_KRW / TOSSINVEST_DAILY_MAX_ORDER_COUNT_USD (기본: 없음)
계좌별·시장별 생성·정정 성공 건수 상한입니다. 국내에 "5", 미국에 "10"을 넣으면 각각 5건·10건으로 제한합니다. 정정도 성공할 때마다 1건으로 셉니다. 취소는 건수에 포함하지 않고 기존 건수를 돌려주지도 않습니다.
한쪽 시장의 한도를 소진해도 다른 시장에는 영향을 주지 않습니다. 한쪽만 설정하면 다른 시장은 건수 제한이 없습니다. 기존 합산 변수 TOSSINVEST_DAILY_MAX_ORDER_COUNT가 남아 있으면 아래 변경 사항의 호환 규칙을 확인하세요.
TOSSINVEST_ALLOWED_SYMBOLS (기본: 없음)
거래를 허용할 종목만 콤마로 나열합니다. 목록에 없는 종목의 생성·정정은 차단됩니다. 예: "005930,AAPL,VOO". 국내는 6자리 숫자 코드, 미국은 티커를 씁니다. 조회 종목을 제한하는 설정은 아닙니다.
TOSSINVEST_MARKET_ORDER_BUFFER_PCT (기본: 3)
수량 기반 시장가 주문의 예산을 계산할 때 직전 체결가(lastPrice)에 적용하는 비율입니다. 국내·미국 모두 같은 방식이며, 설정 범위는 0 이상 100 미만입니다.
주문 방식 | 한도 검사·집계 금액 |
지정가 | 수량 × 주문가격 |
금액 지정 시장가 |
|
수량 지정 시장가 매수 | 수량 × 직전 체결가 × |
수량 지정 시장가 매도 | 수량 × 직전 체결가 × |
기본 p가 3이므로 매수는 +3%, 매도는 −3%를 적용합니다. 국내 주문에 대한 토스의 상·하한가 기반 고액 판정과는 다르며, 실제 체결금액이나 접수 결과를 보장하지 않습니다. 금액 한도에 필요한 가격을 확인하지 못하면 주문을 차단하고, 금액 한도가 없으면 집계 목적만의 시세 조회는 생략합니다.
TOSSINVEST_DATA_DIR / TOSSINVEST_GUARD_STATE_PATH
보통 직접 지정할 필요는 없습니다. 기본 데이터 디렉터리는 다음과 같습니다.
macOS:
~/Library/Application Support/tossinvest-mcpWindows:
%LOCALAPPDATA%/tossinvest-mcpLinux:
$XDG_DATA_HOME/tossinvest-mcp또는~/.local/share/tossinvest-mcp
토큰과 주문 집계는 키별로 나누어 저장합니다. 새 주문 상태 파일은 guard-v4-<키 식별자>.json이며, TOSSINVEST_GUARD_STATE_PATH를 지정하면 그 경로에 .v4-<키 식별자>.json을 붙입니다.
같은 컴퓨터·OS 사용자에서 같은 키의 한도를 공유하려면 모든 MCP 프로세스에 같은 저장 경로와 같은 한도 설정을 사용하세요. 프로세스 간 잠금으로 토큰 발급과 주문 예산을 공유합니다. 다른 컴퓨터나 별도 저장 경로에서 같은 키로 토큰을 발급하면 기존 토큰과 충돌할 수 있습니다. Secret Key는 상태 파일에 저장하지 않습니다.
처음 거래를 켤 때 예시 설정
거래를 처음 켤 때는 한도를 작게 잡아 두는 것을 권장합니다. 아래는 삼성전자 주문만 허용하고 1회 30만 원·일일 100만 원·국내 생성·정정 성공 5건으로 제한한 예시입니다.
{
"mcpServers": {
"tossinvest": {
"command": "npx",
"args": ["-y", "tossinvest-mcp"],
"env": {
"TOSSINVEST_CLIENT_ID": "발급받은-Client-ID",
"TOSSINVEST_CLIENT_SECRET": "발급받은-Client-Secret",
"TOSSINVEST_ACCOUNT": "2",
"TOSSINVEST_ENABLE_TRADING": "true",
"TOSSINVEST_ALLOWED_SYMBOLS": "005930",
"TOSSINVEST_MAX_ORDER_AMOUNT_KRW": "300000",
"TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW": "1000000",
"TOSSINVEST_DAILY_MAX_ORDER_COUNT_KRW": "5"
}
}
}
}TOSSINVEST_ACCOUNT는 계좌 목록에서 확인한 순번으로 바꾸세요. 이 예시는 매도와 시장가를 차단하지 않습니다. 원하는 주문 방식은 AI에게 구체적으로 지시하세요. 두 시장을 모두 거래하려면 USD 금액·건수 한도도 각각 설정합니다.
하루 한도 계산 방식
범위: API 키·계좌·시장별로 분리하고 같은 범위의 매수·매도를 합산합니다. 토스 앱 등 다른 경로의 거래는 포함하지 않습니다.
신규 주문: 접수 전에 예산을 예약하고 접수 결과를 기록합니다. 명확한 거절이면 예약을 해제하지만, 접수 여부가 불명확하면 유지합니다.
정정: 기존 미체결 부분과 대체 주문금액의 차액을 반영합니다. 1회 금액 상한은 대체 주문 전체에 적용합니다.
취소: 실제 취소가 확인된 미체결 부분만 차감하고 체결분은 남깁니다. 차감에는 저장한 기준가격·버퍼를 사용하며 당시 시세로 다시 평가하지 않습니다.
집계 구간: 예약한 시점의 시장별 구간에 기록합니다. 응답이 초기화 이후에 도착해도 원래 구간에 반영합니다. 지난 구간의 주문을 취소해 새 구간의 사용액을 줄이지 않습니다.
조회 범위: 전체 주문을 매번 재조회하지 않고 정정·취소 대상과 미확정 작업만 확인합니다. 앱에서 한 변경·자동 만료·체결가 변동은 상시 재집계하지 않습니다.
건수와 감소 주문: 생성·정정 성공은 각 1건입니다. 일일 한도를 소진해도 취소나 사용액을 줄이는 정정은 허용합니다. 허용된 감액 정정도 성공 건수에는 추가됩니다.
조건주문: 등록·수정 구간에 SINGLE=해당 조건, OCO=큰 조건금액, OTO=두 조건 합계로 집계합니다. 1회 한도는 각 조건에 적용합니다. 나중에 발동한 자식 주문을 다시 집계하지 않으며, 미래 발동일의 금액까지 제한하는 기능은 아닙니다.
취소 확인 불가: 조건주문 취소 뒤 상세 내역이 404로 사라지면 조건별 취소·발동 여부를 추정하지 않고 예산 전액을 유지하며 경고합니다. 이미 발동한 자식 주문은 일반 주문 API로 취소해야 합니다.
요청 식별자:
clientOrderId가 없으면 자동 생성합니다. 같은 키·같은 내용의 생성 요청은 토스의 10분 멱등 기간에 중복 집계하지 않습니다. 자동 복구 재전송은 9분 이내로 제한합니다. 접수 여부가 불명확할 때 새 키로 다시 주문하지 마세요.
환경변수 설명
이름 | 필수 | 설명 |
| 예 | 토스증권 Client ID. 이전 이름 |
| 예 | 토스증권 Client Secret. 이전 이름 |
| 아니오 | 고정할 계좌 순번. 미설정 시 계좌 관련 도구마다 |
| 아니오 | 기본값은 |
| 아니오 | 기본 |
거래 가드레일과 저장 경로 관련 환경변수는 위의 거래 가드레일 표를 참고하세요. 전체 설정 예시는 .env.example에 있습니다. 일반적인 MCP 앱 연결에서는 .env 파일 대신 앱의 env 설정에 값을 넣습니다.
문제 해결
node 명령을 찾을 수 없다고 나옵니다
Node.js가 설치되어 있지 않거나 PATH에 등록되지 않은 상태입니다. Node.js 공식 사이트에서 LTS 버전을 설치한 뒤 터미널을 새로 열고 다시 시도하세요.
허용되지 않은 IP 주소입니다. 오류가 나옵니다
현재 컴퓨터의 공인 IP가 토스증권 Open API 허용 IP 목록에 등록되지 않은 상태입니다.
이 문서의 설치방법 > 3. 허용 IP 등록 단계를 다시 확인해 현재 공인 IP를 등록하세요. 집, 회사, 카페, VPN 등 네트워크가 바뀌면 공인 IP가 바뀔 수 있습니다.
MCP 클라이언트에 도구가 보이지 않습니다
설정 JSON 문법이 올바른지 확인하고, MCP 클라이언트를 완전히 종료한 뒤 다시 실행하세요. Client ID와 Client Secret이 비어 있으면 서버가 시작되지 않습니다. 이 프로그램은 로컬 stdio MCP를 등록할 수 있는 앱에서 사용합니다.
계좌 조회는 되는데 보유 주식 조회가 실패합니다
계좌 목록에서 accountSeq를 확인하고 AI에게 사용할 계좌를 알려주세요. 0.3.0버전 이상은 계좌 1을 자동 선택하지 않습니다. TOSSINVEST_ACCOUNT로 계좌를 고정한 경우에는 다른 계좌를 입력할 수 없습니다.
주문 도구가 보이지 않습니다
정상입니다. 기본값으로는 주문 도구가 등록되지 않습니다. 실제 거래를 허용하려면 TOSSINVEST_ENABLE_TRADING을 true로 설정하고 MCP 클라이언트를 재시작해야 합니다.
거래 기능을 켰는데도 주문이 안 됩니다
계좌 선택, 금액·건수 한도, 종목 허용목록과 토스가 반환한 오류를 확인하세요. confirmOrderAction은 제거되었으므로 입력에서 빼야 합니다. 고액 확인 오류는 사용자 승인 후 confirmHighValueOrder로 처리합니다.
주문 정정 후 기존 orderId로 조회한 내용이 이상합니다
토스증권 주문 정정은 새 orderId를 반환합니다. 정정 응답의 새 ID를 사용하세요. 조건주문 수정도 새 conditionalOrderId를 사용합니다.
접수 여부가 불명확하거나 미확정 작업 때문에 주문이 막힙니다
타임아웃이 났다고 주문이 거절된 것은 아닙니다. 오류의 clientOrderId·대상 주문 ID로 주문 목록/상세를 확인하고, 새 키로 재주문하지 마세요. 미확정 작업이 해결되기 전에는 신규·증액을 제한하며 취소 경로는 유지합니다. 상세 조회는 응답이 확인된 정정·취소의 뒤늦은 확정을 반영할 수 있고, 생성·정정을 재전송하지 않습니다.
하루 한도를 안 넘은 것 같은데 주문이 막힙니다
일일 금액은 매수와 매도를 합산하고 미체결 예약액도 포함합니다. 정정은 성공할 때마다 1건을 더하며, 취소해도 건수는 되돌아오지 않습니다. 국내는 KST 20:01, 미국은 KST 10:01에 초기화합니다. 가격을 확인할 수 없거나 이전 기록을 보수적으로 이월한 경우에도 차단될 수 있습니다.
응답에 _guardStateWarning 또는 _budgetRetained가 붙어 있습니다
접수 응답은 받았으나 한도 기록·최종 상태 확인이 끝나지 않았거나, 취소 후 내역을 확인할 수 없어 예산을 유지했다는 뜻입니다. 새 주문으로 다시 보내지 말고 실제 주문 상태를 확인하세요. 경고가 사라졌다고 체결까지 완료됐다는 의미도 아닙니다.
상태 파일을 읽을 수 없다고 나옵니다
손상된 파일을 자동으로 사용액 0으로 초기화하지 않습니다. 모든 MCP 프로세스를 종료하고 파일을 백업한 뒤 원인을 확인하세요. 파일 삭제는 사용액을 잃게 하므로 한도를 푸는 방법으로 사용하지 마세요.
응답에 _warnings가 붙어 있습니다
폐기된 설정, 이전 환경변수 이름, 상태 이전 관련 안내입니다. 폐기 설정은 시작 로그와 해당 세션의 첫 도구 응답에도 알립니다. 안내에 따라 설정을 바꾼 뒤 재시작하세요. 비밀 값은 경고에 포함하지 않습니다.
오류 및 차단 메시지 목록
이 프로그램이 낼 수 있는 주요 메시지와 의미입니다. 주문 전 검사에서 차단된 요청은 주문 API에 전송하지 않습니다. 반면 접수 불명·접수 후 경고는 이미 전송되었을 수 있으므로 구분해야 합니다.
1) 주문 차단·입력 오류
메시지 키워드 | 의미 | 해결 방법 |
| 사용할 계좌가 없음 | 계좌 목록을 먼저 조회한 뒤 순번 입력 |
| 고정 계좌와 다른 계좌 지정 | 고정 계좌 사용 또는 설정 변경 후 재시작 |
| 허용목록 밖 종목 | 종목과 허용목록 확인 |
| 1회 금액 상한 초과 | 수량·가격·한도 확인 |
| 해당 시장의 일일 금액 상한 도달 | 사용액 확인 후 해당 시장 초기화 시각까지 대기하거나 설정 검토 |
| 해당 시장의 일일 건수 상한 도달 | 시장별 건수와 초기화 시각 확인 |
| 국내 정정에 수량 누락 |
|
| 미국 정정에 수량 입력 |
|
| 주문 방식과 가격 입력 불일치 | 시장가는 가격 제외, 지정가는 가격 확인 |
| 기준가격·통화 확인 불가 | 종목·가격 조회 상태 확인 |
| 앞선 작업의 접수·반영이 미확정 | 해당 요청 식별자로 상태 확인, 새 키로 재주문 금지 |
| 집계 파일 손상·읽기 실패 | 프로세스 종료 후 백업·원인 확인 |
2) 토스 API 오류 (응답 코드/상태)
메시지/코드 | 의미 | 해결 방법 |
| 공인 IP 미등록 | 설치 3단계대로 현재 공인 IP 등록 |
HTTP 401 / | 인증 오류 | Client ID·Client Secret과 키 활성 상태 확인. 같은 키의 별도 토큰 발급 여부 확인 |
HTTP 429 | 요청 한도 초과 | 잠시 후 재시도. 일부 요청은 서버가 제한된 횟수로 자동 재시도 |
| 계좌 정보 필요 |
|
| 고액 주문 확인 필요 | 금액 확인·사용자 승인 후 |
3) 네트워크/연결 오류
메시지 | 의미 | 해결 방법 |
| 연결 실패 | 인터넷·VPN·방화벽· |
| 응답 지연 | 주문 요청이었다면 실제 접수 여부부터 확인 |
| 토큰 발급 실패 | 연결 정보·IP·키 활성 상태 확인 |
4) 주문 접수 후 경고·접수 불명
_guardStateWarning·_budgetRetained 또는 Order acceptance unknown이 보이면 실제 접수·취소 상태를 먼저 확인하세요. 한도 예산은 보수적으로 유지됩니다. 새 요청 식별자로 같은 주문을 반복하지 마세요.
변경 사항 (0.3.0)
추가된 기능
REST 도구 20개 추가: 전체 종목, 종목별 매매동향 5종, 주식 랭킹, 시장 지표 3종, 섹터 5종, 조건주문 5종을 지원합니다. 조회 34개·거래 6개입니다.
최신 주문 입력 반영: 국내
timeInForce=OPG, 시장별 주문 조합·소수점 수량·날짜·종목 개수·페이지네이션 검증을 보완했습니다.일일 한도 개선: 계좌·시장별 금액과 건수를 분리하고 국내 KST 20:01·미국 KST 10:01에 초기화합니다. 생성·정정·취소는 저장한 산정 기준으로 차액을 반영합니다.
공유 상태·장애 복구: 프로세스 내부 토큰 발급을 공유하고, 같은 컴퓨터·OS 사용자·저장 경로의 프로세스 간 토큰·주문 예산 잠금을 추가했습니다. 주문 전 예산 예약과 접수 불명 작업의 식별자 보존·복구를 지원합니다.
수정된 동작과 호환성
변경 | 업데이트할 때 확인할 내용 |
연결 정보 이름 변경 |
|
계좌 1 자동 선택 제거 | ACCOUNT 미설정 시 계좌 관련 도구에 |
| 주문 입력에서 제거. |
매도·시장가 차단 설정 삭제 |
|
계좌 잠금 설정 통합 |
|
고액 확인 인자 유지 |
|
응답 이중 래핑 수정 |
|
시장가 산정 변경 | 호가 → 직전 체결가. 버퍼 기본 5→3%, 매수 +p%·매도 −p% |
일일 건수 상한 분리 |
|
집계 방식·파일 변경 | 시장별 초기화와 이벤트 차액 집계 사용. 기존 파일 백업 후 새 상태로 이전 |
기존 TOSSINVEST_DAILY_MAX_ORDER_COUNT는 호환용으로 읽지만 이제 국내·미국 각각의 기본 상한입니다. 기존 값이 5라면 국내 5건·미국 5건이며, 새 시장별 값이 있으면 우선합니다. 한쪽 시장을 무제한으로 쓰려면 기존 합산 변수를 제거하고 제한할 시장의 새 변수만 설정하세요.
제거된 설정은 경고 후 무시합니다. 이전 이름·폐기 설정 안내는 시작 시 stderr와 해당 세션의 첫 도구 응답 _warnings에 전달하고, 값이나 비밀정보는 출력하지 않습니다. Smithery의 기존 apiKey·secretKey 입력 필드는 유지하며 내부에서는 새 환경변수 이름을 사용합니다.
버그 수정·최적화
금액 한도가 설정된 시장에서만 가격 조회·예산 산정을 수행하도록 수정했습니다. 다른 시장의 한도 때문에 불필요하게 주문이 차단되지 않습니다.
공유 토큰 캐시가 null·빈 토큰 등 잘못된 형식이면 정상적으로 다시 발급하도록 보완했습니다. 고액 확인 오류 안내에도 사용자 승인 필요와 자동 확인값 변경 금지를 명시했습니다.
동시 요청의 토큰 중복 발급, 프로세스 간 주문 집계 덮어쓰기, 키·계좌별 집계 혼합을 수정했습니다.
십진수 금액 연산을 적용하고, 부분체결된 미국 주문 정정의 과대 추정과 멱등 재응답의 금액·건수 중복 집계를 수정했습니다.
상태 파일의 필드·금액·수량·통화를 검증합니다. 손상된 파일이나 불완전한 체결 정보를 0으로 확정하지 않습니다.
주문 응답 유실 시 요청 식별자를 보존하고, 접수 후 저장 실패 시 주문 성공 응답을 유지하면서 미확정 예산을 보수적으로 보존합니다.
불필요한 시세·전체 주문 조회, 상세 조회의 장부 쓰기 잠금, KST 날짜 포매터 재생성을 줄였습니다. 실패한 파일 교체의 임시 파일도 정리합니다.
null·비JSON·응답 본문 수신 오류에서 원래 HTTP 상태와 요청 식별자를 보존하도록 보완했습니다.
조건주문 취소의 정상
204 No Content를 지원합니다. 취소 후 상세가 404로 사라지면 예산을 환급하지 않고 유지하며 경고합니다. 상세 조회는 생성·정정을 재전송하지 않습니다.SDK를 1.32.1로 올렸습니다. 개발용 UI·mock 서버·검증 스크립트·테스트 자료는 GitHub·npm 배포 대상에서 제외했고, CI는 타입 검사·빌드·패키징을 확인합니다.
업데이트 방법
npm에 새 버전이 올라와도 설치본이나 실행 중인 MCP가 자동 교체되지는 않습니다.
최신 버전 확인 후 실행:
args를["-y", "--prefer-online", "tossinvest-mcp@latest"]로 설정하면 다음 실행 시 최신 태그를 확인하는 방식으로 사용할 수 있습니다.전역·프로젝트 설치본: 업데이트하거나 재설치해야 합니다. 단순한
npx tossinvest-mcp는 로컬 설치본·캐시·npm 설정의 영향을 받아 항상 최신이라고 보장하지 않습니다.
설정을 바꾸거나 업데이트한 뒤에는 MCP 클라이언트를 완전히 종료했다가 다시 실행하세요. 별도의 자동 업데이터는 제공하지 않습니다.
면책조항
이 프로그램은 토스증권 Open API를 MCP에서 사용할 수 있게 연결해 주는 도구입니다. 투자 자문, 투자 권유, 매매 추천, 수익 보장 서비스를 제공하지 않습니다.
이 프로그램을 사용해 조회한 정보, AI가 생성한 답변, AI가 제안한 주문 내용은 부정확하거나 지연되거나 사용자의 의도와 다를 수 있습니다. 모든 투자 판단과 주문 실행 및 프로그램 사용의 최종 책임은 사용자에게 있습니다.
거래 기능을 켜고 주문 생성, 정정, 취소 도구를 사용하는 경우 실제 계좌에 실제 주문이 전송될 수 있습니다. 주문 전 종목, 가격, 수량, 주문 유형, 계좌를 반드시 직접 확인하세요.
현재 이 프로젝트는 개발중인 프로젝트로서, 이 프로젝트의 개발자와 배포자는 이 프로그램 사용으로 발생하는 투자 손실, 주문 실수, API 장애, 데이터 오류, 클라이언트 오작동, AI 응답 오류. 본 프로그램 오류 등에 대해 책임지지 않습니다.
라이선스
MIT License
기타
토스증권 Open API 공식 문서: 개발자 문서
README.md 파일 작성 등 일부 작업에 생성형 AI의 도움을 받았음을 밝힙니다.
Available Tools
36 toolstoss_get_accountsToss Get AccountsARead-only
List Toss Securities accounts available to the configured Open API credentials.
Inputs: no named parameters.
toss_get_buying_powerToss Get Buying PowerBRead-only
Get available buying power for an account. currency is required: KRW for Korean stocks, USD for US stocks.
Inputs: currency (required), accountSeq (required).
toss_get_candlesToss Get CandlesBRead-only
KR/US stock 1-minute or daily OHLCV. count defaults to 20 (max 200); set it on the first call. Pass nextBefore as before (ISO 8601 with timezone).
Inputs: symbol (required), interval (required), count, before, +1 more.
toss_get_commissionsToss Get CommissionsBRead-only
Get trading commission information for an account.
Inputs: accountSeq (required).
toss_get_conditional_orderToss Get Conditional OrderCRead-only
Get one conditional order by conditionalOrderId.
Inputs: accountSeq (required), conditionalOrderId (required).
toss_get_conditional_ordersToss Get Conditional OrdersBRead-only
List conditional orders. If hasNext, pass nextCursor as cursor.
Inputs: status (required), accountSeq (required), limit, cursor, +1 more.
toss_get_exchange_rateToss Get Exchange RateBRead-only
Get KRW/USD or USD/KRW exchange rate. Optional dateTime is ISO 8601 with timezone.
Inputs: baseCurrency (required), quoteCurrency (required), dateTime.
toss_get_holdingsToss Get HoldingsARead-only
Get account holdings and valuation; optionally filter by symbol.
Inputs: accountSeq (required), symbol.
toss_get_investor_trading_rankings투자자별 순매수·순매도 랭킹 조회ARead-only
국내 주식·ETF의 외국인·기관·개인 순매수/순매도 랭킹(KRW). 최근 영업일만. count는 투자자·방향별 적용(기본 10, 최대 100); 첫 호출에 필요한 건수 지정. 투자자별 rankedAt 확인; 장중 개인은 전 영업일일 수 있습니다. 시세 미포함.
Inputs: count.
toss_get_kr_market_calendarToss Get KR Market CalendarBRead-only
Get Korean market calendar and session hours. date is optional YYYY-MM-DD.
Inputs: date.
toss_get_market_indicator_candles시장 지표 캔들 차트 조회ARead-only
국내 지수·국채 OHLCV, 최신순. 지수만 분봉 지원; 국채는 일봉만. count 기본 20, 최대 200; 첫 호출에 필요한 봉 수 지정. nextBefore를 시간대 포함 ISO 8601 값 그대로 before에 전달.
Inputs: symbol (required), interval (required), count, before.
toss_get_market_indicator_investor_trading투자자별 매매대금 조회ARead-only
코스피·코스닥 투자자별 매수·매도 거래대금(KRW). 등록·미등록 외국인 합산, 기관 세부 분류 포함. 당일 잠정치; updatedAt 확인. 다음 페이지: nextUntil → until.
Inputs: symbol (required), interval (required), count, until.
toss_get_market_indicator_prices시장 지표 현재가 조회ARead-only
국내 지수(KOSPI·KOSDAQ)와 한국 국채(KR_BOND_*) 현재가. 지수는 포인트, 국채는 수익률(%). symbols는 쉼표 구분, 최대 200개.
Inputs: symbols (required).
toss_get_orderToss Get OrderBRead-only
Get one regular order by orderId.
Inputs: orderId (required), accountSeq (required).
toss_get_orderbookToss Get OrderbookBRead-only
Get orderbook data for one KRX or US stock symbol.
Inputs: symbol (required).
toss_get_ordersToss Get OrdersBRead-only
List regular orders. If hasNext, pass nextCursor as cursor. OPEN ignores limit and cursor.
Inputs: status (required), accountSeq (required), to, from, +3 more.
toss_get_price_limitsToss Get Price LimitsBRead-only
Get upper and lower price limits for one KRX or US stock symbol.
Inputs: symbol (required).
toss_get_pricesToss Get PricesARead-only
Get current prices for up to 200 comma-separated KRX or US stock symbols.
Inputs: symbols (required).
toss_get_rankings주식 랭킹 조회ARead-only
국내·미국 주식의 시장·기간별 랭킹. count 기본 20, 최대 100; 첫 호출에 필요한 건수 지정. TOP_GAINERS/TOP_LOSERS는 realtime 불가. TOSS_SECURITIES_*는 토스 체결 기준. 급등락 기준가는 기간 시작가, 그 외는 전일 기준가. 데이터가 없으면 빈 목록.
Inputs: type (required), duration (required), marketCountry (required), count, +1 more.
toss_get_sector섹터 상세 조회ARead-only
섹터 상세·계층 및 선택한 시장의 기간별 등락률(소수비율). 미제공 기간은 null. sectorId는 toss_list_sectors에서 확인하세요.
Inputs: sectorId (required), marketCountry (required).
toss_get_sector_etfs섹터 관련 ETF 조회BRead-only
해당 섹터의 ETF 심볼과 이름. 하위 섹터는 제외합니다. 시세는 toss_get_prices를 사용하세요.
Inputs: sectorId (required), marketCountry (required).
toss_get_sector_rankings섹터 랭킹 조회ARead-only
시장·기간별 섹터 등락률 또는 거래대금 랭킹. 대·중분류만, 최대 100위. 미국 금액도 KRW 환산; 데이터가 없으면 빈 목록.
Inputs: type (required), duration (required), marketCountry (required).
toss_get_sector_stocks섹터 구성 주식 조회ARead-only
섹터와 하위 섹터의 보통주 전체를 선택한 시장 기준 시가총액순으로 조회합니다. 거래량·거래대금은 당일 누적, 미국 금액도 KRW 환산.
Inputs: sectorId (required), marketCountry (required).
toss_get_sellable_quantityToss Get Sellable QuantityCRead-only
Get sellable quantity for one symbol in an account.
Inputs: symbol (required), accountSeq (required).
toss_get_stock_credit_trades신용거래 동향 조회ARead-only
국내 종목의 신용융자·신용대주 일별 수량(주)과 비율. 기관 간 대차와 별개. 미제공 항목은 null, 최신 기록은 전 영업일. 다음 페이지: nextUntil → until.
Inputs: symbol (required), count, until.
toss_get_stock_investor_trading투자자별 매매동향 조회ARead-only
국내 종목의 투자자별 일별 매수·매도·순매수 거래량(주). KRX·NXT 합산, 외국인은 등록 기준. 기관 세부·외국인 보유·CFD 포함. 장중 잠정치에서 미제공 항목은 null; updatedAt 확인. 다음 페이지: nextUntil → until.
Inputs: symbol (required), count, until.
toss_get_stock_program_trades프로그램매매 동향 조회ARead-only
국내 종목의 차익·비차익 프로그램 일별 매수·매도·순매수 거래량(주). KRX만 집계하며 당일은 변동 가능. 다음 페이지: nextUntil → until.
Inputs: symbol (required), count, until.
toss_get_stocksToss Get StocksARead-only
Get stock master data for up to 200 comma-separated KRX or US stock symbols.
Inputs: symbols (required).
toss_get_stock_securities_lending대차거래 동향 조회BRead-only
국내 종목의 기관 간 일별 대차 체결·상환·잔고(수량·KRW). 신용대주와 별개. 다음 페이지: nextUntil → until.
Inputs: symbol (required), count, until.
toss_get_stock_short_selling공매도 동향 조회BRead-only
국내 종목의 일별 공매도 거래량·거래대금(KRW)·비중. 비중의 분모는 시간외 포함 당일 거래량·거래대금이며 미제공은 null. 다음 페이지: nextUntil → until.
Inputs: symbol (required), count, until.
toss_get_stock_warningsToss Get Stock WarningsARead-only
Get buy warning flags for one KRX or US stock symbol.
Inputs: symbol (required).
toss_get_tradesToss Get TradesBRead-only
Get recent trades for one KRX or US stock symbol. Optional count defaults to 20 (max 50); set the needed count on the first call.
Inputs: symbol (required), count.
toss_get_transactionsToss Get TransactionsARead-only
Account trades, transfers, FX, dividends, interest and fees (KR/US stocks, options and bonds; see assetClass). Dates use KST settlement day (expected for unsettled); omit the to filter to include future settlements. Unsettled first, newest first within each group. Follow hasNext even on empty pages; pass nextCursor unchanged and clear it if account or filters change. No order IDs.
Inputs: accountSeq (required), to, from, limit, +2 more.
toss_get_us_market_calendarToss Get US Market CalendarBRead-only
Get US market calendar and session hours. date is optional YYYY-MM-DD in US local date.
Inputs: date.
toss_list_sectors섹터 목록 조회ARead-only
토스 섹터 분류 전체와 계층 정보(depth·parentSectorId)를 조회합니다. 다른 섹터 도구에서 반환된 sectorId를 사용하세요.
Inputs: no named parameters.
toss_list_stocks마켓별 전체 종목 조회ARead-only
거래소별 토스 거래 가능 종목 전체를 심볼순으로 반환합니다. 페이지 없음; status·securityType·commonShare로 좁히세요. 개별 종목 상세는 toss_get_stocks.
Inputs: market (required), status, commonShare, symbolsOnly, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 36 tools
Most tools are clearly separated by resource and action, with descriptions clarifying scopes such as stock vs. market-indicator data and the three ranking variants. Minor overlap exists between toss_list_stocks and toss_get_stocks, and among ranking tools, but these are unlikely to cause frequent misselection.
Every tool uses the toss_ prefix followed by snake_case verb_noun naming (e.g. toss_get_prices, toss_list_sectors, toss_get_conditional_order). The only variation is get vs. list, which is predictable and semantically appropriate.
At 36 tools, the surface is heavy for an investment API and includes many granular endpoints that could be consolidated, such as five separate stock trading-data tools and four order-lookup tools. This exceeds the typical 25+ threshold where count starts to feel excessive.
The server broadly covers market data, indicators, sectors, rankings, account holdings, transactions, buying power, sellable quantity, commissions, and order retrieval. However, core trading lifecycle operations like creating, amending, or canceling orders are missing, leaving a notable dead end for a trading-oriented domain.
Maintenance
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
Open-source MCP server for Zerodha Kite Connect. Portfolio, market data, backtesting, alerts.
Multi-tenant FastMCP server for Charles Schwab brokerage data, monetized via DPYC Tollbooth
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server wrapping Toss Securities Open API, enabling stock price queries and trading for Korean and US stocks via natural language.36265 npmMIT
- AlicenseCqualityCmaintenanceSafe-by-default MCP server for the official Toss Securities Open API, providing read-only market and account data with optional order operations protected by multiple safety gates.272MIT
- FlicenseAqualityDmaintenanceEnables MCP clients to read Toss Securities market data and account info, and optionally place real-money orders.20-
- AlicenseAqualityDmaintenanceA local MCP server that automatically generates tools from Toss Securities' official OpenAPI spec, enabling real API calls with multi-layered order safety and OAuth 2.0 authentication.361MIT