Tossinvest MCP

tossinvest-mcp

프로그램 개요

현재 버전: 0.3.0

tossinvest-mcp는 토스증권 Open API(현재가 조회, 주문, 잔고 조회 등)를 OpenAI 서비스, Claude Desktop, Cursor 같은 MCP 지원 프로그램에서 사용할 수 있게 해주는 로컬 MCP 서버입니다.

쉽게 말해, 이 프로그램을 MCP 클라이언트에 등록하면 AI에게 다음처럼 요청할 수 있습니다.

삼성전자 현재가를 조회해줘.

내 토스증권 보유 주식을 보여줘.

삼성전자 1주를 주문해줘.

이 프로그램은 사용자의 컴퓨터에서만 실행됩니다.

가장 중요한 주의사항

토스증권 Open API에는 샌드박스나 모의투자 환경이 없습니다.

거래 기능을 켜면 실제 계좌에 실제 주문을 생성, 정정, 취소할 수 있습니다. 처음 사용할 때는 반드시 거래 기능을 켜지 말고 조회 기능부터 확인하세요.

기본 설정에서는 주문 생성, 정정, 취소 도구가 등록되지 않습니다.

프로그램으로 할 수 있는 기능 및 특징

거래 기능을 켜지 않아도 아래 기능을 사용할 수 있습니다.

• 국내/미국 주식 현재가 조회
• 호가 조회
• 최근 체결 내역 조회
• 캔들 차트 조회
• 상한가/하한가 조회
• 종목 기본 정보 조회
• 전체 종목 목록 조회
• 매수 유의사항 조회
• 종목별 투자자·프로그램·공매도·신용거래·대차거래 동향 조회
• 주식 랭킹 조회
• 시장 지표 현재가·차트·투자자 매매동향 조회
• 섹터 목록·상세·랭킹·소속 주식·ETF 조회
• 환율 조회
• 국내/미국 장 운영 시간 조회
• 계좌 목록 조회
• 보유 주식 조회
• 매수 가능 금액 조회
• 판매 가능 수량 조회
• 매매 수수료 조회
• 주문 목록 조회
• 주문 상세 조회
• 조건주문 목록·상세 조회

거래 기능을 켠 경우 사용할 수 있는 도구:

• toss_create_order: 주문 생성
• toss_modify_order: 주문 정정
• toss_cancel_order: 주문 취소
• toss_create_conditional_order: 조건주문 생성
• toss_modify_conditional_order: 조건주문 수정
• toss_cancel_conditional_order: 조건주문 취소

0.3.0은 REST 도구 20개를 추가해 조회 34개·거래 6개를 제공합니다. 로컬 stdio 방식이며 WebSocket이나 원격 HTTP/SSE 서버는 제공하지 않습니다.

특징:

• npx로 실행되므로 별도 프로그램 설치 과정이 짧습니다.
• Client ID와 Client Secret은 환경변수로 전달합니다. 이전 이름인 API Key·Secret Key 환경변수도 호환됩니다.
• OAuth 토큰은 내부에서 자동 발급하고, 만료 60초 전에 갱신합니다. 같은 컴퓨터·OS 사용자·저장 경로에서는 여러 프로세스가 토큰과 주문 집계를 공유합니다.
• 계좌가 필요한 기능은 AI가 계좌 목록을 확인한 뒤 accountSeq를 입력합니다. 계좌 1을 자동 선택하지 않습니다.
• TOSSINVEST_ACCOUNT를 설정하면 해당 계좌로 고정하며, 다른 계좌를 지정한 호출은 거절합니다.
• 일반 주문·조건주문 생성, 정정, 취소 기능은 기본적으로 꺼져 있습니다.
• 거래 기능을 켜면 confirmOrderAction 없이 주문할 수 있습니다. 매도·시장가 차단 설정도 제거되었습니다.
• 1회 금액 한도, 시장별 일일 금액·건수 한도, 종목 허용목록은 필요한 항목만 환경변수로 설정할 수 있습니다. (아래 거래 가드레일 참고)

설치방법

아래 순서대로 진행하면 됩니다.

1. Node.js 설치 확인

터미널 또는 PowerShell을 열고 아래 명령어를 입력합니다.

node -v

v20 이상이 나오면 다음 단계로 넘어가면 됩니다.

Node.js가 없거나 버전이 낮다면 Node.js 공식 사이트에서 LTS 버전을 설치한 뒤 터미널을 새로 열어 다시 확인하세요.

2. 토스증권 Open API 연결 정보 준비

토스증권 WTS에 로그인한 뒤 Open API 설정 화면으로 이동합니다.

그 화면에서 아래 값을 발급받아 둡니다.

• Client ID
• Client Secret

이 두 값은 MCP 설정에 넣어야 합니다. 다른 사람에게 공유하지 마세요.

3. 허용 IP 등록

토스증권 Open API는 허용된 IP에서만 호출할 수 있습니다. 이 설정이 빠져 있으면 허용되지 않은 IP 주소입니다. 같은 오류가 발생합니다.

먼저 현재 컴퓨터의 공인 IP를 확인합니다. 아래 명령어를 사용하세요.

PowerShell (Windows):

(Invoke-WebRequest -UseBasicParsing https://api.ipify.org).Content

macOS 또는 Linux 터미널:

curl https://api.ipify.org

나온 IP 주소를 토스증권 WTS의 Open API 설정 화면에서 허용 IP 목록에 추가합니다.

대략적인 흐름:

1. 토스증권 WTS에 로그인합니다.
2. 설정 - Open API 메뉴로 이동합니다.
3. 허용 IP 관리 영역을 찾습니다.
4. 위에서 확인한 공인 IP를 추가합니다.

4. MCP 클라이언트에 등록

MCP 클라이언트의 설정 파일 또는 MCP Servers 설정 화면에 아래 내용을 추가합니다.

{
  "mcpServers": {
    "tossinvest": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "TOSSINVEST_CLIENT_ID": "발급받은-Client-ID",
        "TOSSINVEST_CLIENT_SECRET": "발급받은-Client-Secret"
      }
    }
  }
}

설정 후 MCP 클라이언트를 완전히 종료했다가 다시 실행하세요.

처음 실행할 때 npm이 지정한 버전의 tossinvest-mcp 패키지를 내려받습니다. 위 예시는 0.3.0을 고정해 실행합니다.

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", "[email protected]"],
      "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", "[email protected]"],
      "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".

한눈에 보기 (요약 표)

이름	기본값	한 줄 설명
TOSSINVEST_MAX_ORDER_AMOUNT_KRW	없음	1회 주문 금액 상한(원)
TOSSINVEST_MAX_ORDER_AMOUNT_USD	없음	1회 주문 금액 상한(달러)
TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW	없음	국내 일일 주문 금액 상한(원)
TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD	없음	미국 일일 주문 금액 상한(달러)
TOSSINVEST_DAILY_MAX_ORDER_COUNT_KRW	없음	국내 일일 생성·정정 성공 건수 상한
TOSSINVEST_DAILY_MAX_ORDER_COUNT_USD	없음	미국 일일 생성·정정 성공 건수 상한
TOSSINVEST_ALLOWED_SYMBOLS	없음	거래 가능 종목만 지정
TOSSINVEST_MARKET_ORDER_BUFFER_PCT	3	수량 시장가 주문의 예산 계산 버퍼(%)
TOSSINVEST_DATA_DIR	OS 데이터 폴더	토큰과 일일 집계를 공유할 디렉터리
TOSSINVEST_GUARD_STATE_PATH	자동 지정	기존 상태 파일 경로 및 새 상태 파일명 접두사

옵션별 상세 설명

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 미만입니다.

주문 방식	한도 검사·집계 금액
지정가	수량 × 주문가격
금액 지정 시장가	orderAmount
수량 지정 시장가 매수	수량 × 직전 체결가 × (1 + p/100)
수량 지정 시장가 매도	수량 × 직전 체결가 × (1 - p/100)

기본 p가 3이므로 매수는 +3%, 매도는 −3%를 적용합니다. 국내 주문에 대한 토스의 상·하한가 기반 고액 판정과는 다르며, 실제 체결금액이나 접수 결과를 보장하지 않습니다. 금액 한도에 필요한 가격을 확인하지 못하면 주문을 차단하고, 금액 한도가 없으면 집계 목적만의 시세 조회는 생략합니다.

TOSSINVEST_DATA_DIR / TOSSINVEST_GUARD_STATE_PATH

보통 직접 지정할 필요는 없습니다. 기본 데이터 디렉터리는 다음과 같습니다.

• macOS: ~/Library/Application Support/tossinvest-mcp
• Windows: %LOCALAPPDATA%/tossinvest-mcp
• Linux: $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", "[email protected]"],
      "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 금액·건수 한도도 각각 설정합니다.

1日の上限の計算方法

• 範囲: API キー・口座・市場ごとに分け、同じ範囲内の買い・売りを合算します。トスアプリなど、別の経路での取引は含みません。
• 新規注文: 受付前に予算を予約し、受付結果を記録します。明確に拒否された場合は予約を解除しますが、受付の有無が不明な場合は維持します。
• 訂正: 既存の未約定部分と代替注文金額の差額を反映します。1回あたりの金額上限は、代替注文全体に適用します。
• 取消: 実際に取消が確認された未約定部分のみ差し引き、約定分は残します。差し引きには保存した基準価格・バッファーを使用し、その時点の相場で再評価しません。
• 集計区間: 予約した時点の市場別区間に記録します。応答がリセット後に届いても、元の区間に反映します。過去の区間の注文を取り消しても、新しい区間の使用額は減りません。
• 照会範囲: すべての注文を毎回再照会せず、訂正・取消の対象と未確定の処理のみを確認します。アプリで行った変更・自動失効・約定価格の変動は、常時再集計しません。
• 件数と減額注文: 作成・訂正の成功はそれぞれ1件です。1日の上限に達していても、取消や使用額を減らす訂正は許可されます。許可された減額訂正も成功件数に加算されます。
• 条件注文: 登録・変更した区間に、SINGLE は該当条件、OCO は金額の大きい条件、OTO は2つの条件の合計として集計します。1回あたりの上限は各条件に適用します。後で発動した子注文は再集計せず、将来の発動日の金額まで制限する機能ではありません。
• 取消を確認できない場合: 条件注文の取消後、詳細が404で見つからなくなった場合は、条件ごとの取消・発動状況を推測せず、予算全額を維持して警告します。すでに発動した子注文は、通常注文 API で取り消す必要があります。
• リクエスト識別子: clientOrderId がない場合は自動生成します。同じキー・同じ内容の作成リクエストは、トスの10分間の冪等期間中は重複して集計しません。自動復旧の再送は9分以内に制限します。受付の有無が不明な場合は、新しいキーで再注文しないでください。

環境変数の説明

名前	必須	説明
TOSSINVEST_CLIENT_ID	はい	トス証券 Client ID。以前の名前 TOSSINVEST_API_KEY も使用できます
TOSSINVEST_CLIENT_SECRET	はい	トス証券 Client Secret。以前の名前 TOSSINVEST_SECRET_KEY も使用できます
TOSSINVEST_ACCOUNT	いいえ	固定する口座の順番。未設定の場合、口座関連ツールごとに accountSeq を入力
TOSSINVEST_BASE_URL	いいえ	デフォルトは https://openapi.tossinvest.com
TOSSINVEST_ENABLE_TRADING	いいえ	デフォルトは false。true の場合、通常注文・条件注文の作成・訂正・取消ツールを登録

取引ガードレールと保存先に関する環境変数については、上記の 取引ガードレール の表を参照してください。設定の全例は .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日の上限を超えていないように見えるのに注文がブロックされます

1日の金額は買いと売りを合算し、未約定の予約額も含みます。訂正は成功するたびに1件追加され、取り消しても件数は戻りません。韓国国内市場は KST 20:01、米国市場は KST 10:01 にリセットされます。価格を確認できない場合や、過去の記録を保守的に繰り越した場合も、ブロックされることがあります。

応答に _guardStateWarning または _budgetRetained が付いています

受付応答は受け取ったものの、上限の記録・最終状態の確認が終わっていないか、取消後に明細を確認できず、予算を維持したことを意味します。新しい注文として再送せず、実際の注文状態を確認してください。警告が消えても、約定まで完了したことを意味するわけではありません。

状態ファイルを読み取れないと表示されます

破損したファイルを自動的に使用額0で初期化することはありません。すべての MCP プロセスを終了してファイルをバックアップし、原因を確認してください。ファイルを削除すると使用額が失われるため、上限を解除する方法として使用しないでください。

応答に _warnings が付いています

廃止された設定、以前の環境変数名、状態の移行に関する案内です。廃止された設定については、起動ログと、そのセッションの最初のツール応答でも通知します。案内に従って設定を変更し、再起動してください。警告に秘密の値が含まれることはありません。

エラーおよびブロックメッセージの一覧

このプログラムが出力する主なメッセージとその意味です。注文前の検査でブロックされたリクエストは、注文 API に送信されません。一方、受付が不明な場合や受付後の警告は、すでに送信されている可能性があるため、区別する必要があります。

1) 주문 차단·입력 오류

메시지 키워드	의미	해결 방법
accountSeq is required	사용할 계좌가 없음	계좌 목록을 먼저 조회한 뒤 순번 입력
Account is fixed to TOSSINVEST_ACCOUNT	고정 계좌와 다른 계좌 지정	고정 계좌 사용 또는 설정 변경 후 재시작
is not in TOSSINVEST_ALLOWED_SYMBOLS	허용목록 밖 종목	종목과 허용목록 확인
exceeds per-order limit	1회 금액 상한 초과	수량·가격·한도 확인
Daily order amount limit reached	해당 시장의 일일 금액 상한 도달	사용액 확인 후 해당 시장 초기화 시각까지 대기하거나 설정 검토
Daily order count limit reached (KRW/USD)	해당 시장의 일일 건수 상한 도달	시장별 건수와 초기화 시각 확인
KR modify requires quantity	국내 정정에 수량 누락	quantity 입력
US modify forbids quantity	미국 정정에 수량 입력	quantity 제외
MARKET forbids price / LIMIT requires price	주문 방식과 가격 입력 불일치	시장가는 가격 제외, 지정가는 가격 확인
Cannot value / Cannot determine currency	기준가격·통화 확인 불가	종목·가격 조회 상태 확인
unresolved prior operation	앞선 작업의 접수·반영이 미확정	해당 요청 식별자로 상태 확인, 새 키로 재주문 금지
Cannot read guard state (not reset)	집계 파일 손상·읽기 실패	프로세스 종료 후 백업·원인 확인

2) 토스 API 오류 (응답 코드/상태)

메시지/코드	의미	해결 방법
허용되지 않은 IP 주소입니다.	공인 IP 미등록	설치 3단계대로 현재 공인 IP 등록
HTTP 401 / invalid-token	인증 오류	Client ID·Client Secret과 키 활성 상태 확인. 같은 키의 별도 토큰 발급 여부 확인
HTTP 429	요청 한도 초과	잠시 후 재시도. 일부 요청은 서버가 제한된 횟수로 자동 재시도
account-header-required	계좌 정보 필요	TOSSINVEST_ACCOUNT 또는 요청의 accountSeq 확인
confirm-high-value-required	고액 주문 확인 필요	금액 확인·사용자 승인 후 confirmHighValueOrder: true 전달

3) 네트워크/연결 오류

메시지	의미	해결 방법
Failed to connect to Toss Open API.	연결 실패	인터넷·VPN·방화벽·TOSSINVEST_BASE_URL 확인
Toss Open API request timed out after 20s.	응답 지연	주문 요청이었다면 실제 접수 여부부터 확인
Invalid OAuth token response / OAuth 토큰 발급 오류	토큰 발급 실패	연결 정보·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 사용자·저장 경로의 프로세스 간 토큰·주문 예산 잠금을 추가했습니다. 주문 전 예산 예약과 접수 불명 작업의 식별자 보존·복구를 지원합니다.

수정된 동작과 호환성

변경	업데이트할 때 확인할 내용
연결 정보 이름 변경	TOSSINVEST_CLIENT_ID·TOSSINVEST_CLIENT_SECRET 사용. 기존 TOSSINVEST_API_KEY·TOSSINVEST_SECRET_KEY도 호환하며 새 이름 우선
계좌 1 자동 선택 제거	ACCOUNT 미설정 시 계좌 관련 도구에 accountSeq 입력. ACCOUNT 설정 시 해당 계좌로 고정
confirmOrderAction 삭제	주문 입력에서 제거. TOSSINVEST_REQUIRE_ORDER_CONFIRMATION도 제거
매도·시장가 차단 설정 삭제	TOSSINVEST_ALLOW_SELL_ORDERS·TOSSINVEST_ALLOW_MARKET_ORDERS 제거. 거래 활성화 시 매도·시장가 가능
계좌 잠금 설정 통합	TOSSINVEST_LOCK_ACCOUNT 제거. ACCOUNT 설정 자체로 계좌 고정
고액 확인 인자 유지	confirmHighValueOrder를 토스에 그대로 전달. 고액 여부를 로컬에서 중복 판정하거나 자동 승인하지 않음
응답 이중 래핑 수정	structuredContent.result.result → structuredContent.result. 텍스트 JSON도 같은 구조
시장가 산정 변경	호가 → 직전 체결가. 버퍼 기본 5→3%, 매수 +p%·매도 −p%
일일 건수 상한 분리	TOSSINVEST_DAILY_MAX_ORDER_COUNT_KRW·TOSSINVEST_DAILY_MAX_ORDER_COUNT_USD로 각각 설정
집계 방식·파일 변경	시장별 초기화와 이벤트 차액 집계 사용. 기존 파일 백업 후 새 상태로 이전

기존 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는 타입 검사·빌드·패키징을 확인합니다.

기존 상태 파일 이전

업그레이드 전에 기존 MCP 프로세스를 모두 종료하세요. 이전 guard-state.json은 백업 후 현재·전일의 검증 가능한 기록을 중복 제거해 시장별 초기 사용액·건수로 한 번 가져옵니다. 이전 파일에는 API 키 식별자가 없고 미체결 단가를 완전히 복구할 수 없어, 과거 취소 환급은 추정하지 않습니다. 손상 파일을 조용히 0으로 초기화하지 않습니다.

개발 중인 0.3.0의 v3(자정 기준) 장부가 있으면 백업 후 v4로 보수적으로 이전합니다. 첫 집계 구간의 사용액이 실제보다 클 수 있습니다. 시장을 구분할 수 없는 과거 합산 건수는 각 시장 상한에 보수적으로 적용하고, 두 시장이 각각 다음 초기화 시각을 지날 때까지 유지합니다.

구버전으로 돌아갈 때는 백업 파일과 기존 설정을 사용해야 하며 새 버전에서 추가한 거래는 구버전 파일에 반영되지 않습니다. 구·신 버전을 같은 키로 동시에 실행하지 마세요.

업데이트 방법

npm에 새 버전이 올라와도 설치본이나 실행 중인 MCP가 자동 교체되지는 않습니다.

• 버전 고정: 이 문서의 [email protected]은 해당 버전을 유지합니다. 업데이트하려면 버전을 직접 바꾸세요.
• 최신 버전 확인 후 실행: 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의 도움을 받았음을 밝힙니다.