한국어 · English

_{설치 한 줄 → QR 로그인 → 바로 조회. 지금 시작 ↓}

빠른 시작 · 지원 범위 · 명령 목록 · FAQ · 문서 · 후원

[!WARNING] 이 프로젝트는 토스증권 공식 제품이 아닙니다. 공식 Open API 키를 연결하면 해당 기능은 토스가 공식 지원하는 경로로 동작하지만, 그 외 기능은 토스 웹 내부 API를 비공식적으로 사용하며 이는 토스증권 이용약관(TOS) 위반에 해당할 수 있습니다. API는 예고 없이 변경될 수 있고, 사용으로 인한 계좌 제한·손실·기타 불이익에 대해 개발자는 어떠한 책임도 지지 않습니다. 본인의 판단과 책임 하에 사용하세요.

[!IMPORTANT] 거래 기능은 설치 직후 모두 꺼져 있습니다. config.json에서 기능별로 직접 허용해야만 실행됩니다.

_{WORKS WITH}

                             

후원

_{현재 1분이 제 오픈소스 작업을 후원하고 있습니다 (일회성 포함). 후원은 tossinvest-cli 를 포함한 제 작업 전반에 쓰입니다.}

빠른 시작

어떻게 쓸지에 따라 고르세요.

• AI 에이전트(Claude·Codex·Cursor…)로 쓴다 → MCP 가 가장 간단합니다. 한 번 등록하면 (claude mcp add tossctl tossctl mcp) 에이전트가 자연어로 알아서 다룹니다. → MCP 빠른 시작
• 터미널·스크립트·자동화, 또는 전 기능(관심종목 등 WTS 쓰기·실시간 포함) → CLI. 아래에서 바로 시작하세요. ↓

둘 다 로그인 한 번이면 되고, 같은 tossctl 을 씁니다. 자세한 차이는 CLI 와 MCP — 언제 무엇을.

에이전트용

Install tossinvest-cli:
  curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh
(macOS/Linux) or GitHub Releases (Windows).

Run `tossctl doctor` to verify setup, then complete browser login with
`tossctl auth login`. Use read-only commands first (account, portfolio, quote).
Trading actions stay disabled until config.json explicitly allows them.
Always run `tossctl order preview` before any trading mutation.

사람용

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex

설치 확인:

tossctl version
tossctl doctor
tossctl auth login
tossctl account summary --output json

설치 후 새 버전이 나오면 tossctl update 로 갱신할 수 있습니다 (Homebrew로 설치했다면 brew upgrade tossctl-cli 로 자동 위임됩니다).

auth login에는 Google Chrome과 Python이 필요하며, 설치 스크립트가 자동으로 설정합니다. Windows, Homebrew, 소스 빌드 등 다른 설치 방법은 설치 섹션을 참고하세요.

QR 스캔 후 폰에 뜨는 "이 기기 로그인 유지" 확인 프롬프트까지 꼭 눌러주세요. 이 2차 확인을 건너뛰면 세션이 약 1시간 idle 후 만료되어 재로그인이 필요해집니다. 정상 캡처 여부는 tossctl auth status 의 Persistence: persistent cookie (expires ...) 로 확인할 수 있습니다.

GUI 없는 환경 (SSH 서버·CI): tossctl auth login --headless [--qr-output /tmp/toss-qr.png]. QR URL 과 확인 문자(answerLetter)가 stderr 로 출력되며, URL 을 폰으로 전달해 탭하면 카메라 없이 Toss 앱에서 인증할 수 있습니다. --qr-output 파일은 0600 권한으로 저장됩니다.

세션 연장

토스 서버는 SESSION 쿠키(1년 Max-Age)와 별개로 약 7일짜리 활성 만료 시계를 운영합니다. 만료 24시간 전부터 모든 명령에 다음과 같은 stderr 경고가 표시됩니다.

⚠ session expires in ~18h; run `tossctl auth extend` to renew

tossctl auth extend 는 폰의 토스 앱에 푸시를 보내고 승인을 기다립니다.

$ tossctl auth extend
Waiting for approval in the Toss app on your phone...
✓ Extension complete. New expiry: 2026-05-13 07:03 KST (took 4s)

기본 timeout 은 120초이며 --timeout 60s 처럼 단축할 수 있습니다.

만료되기 전에 자동으로 챙기기

폰 승인은 토스의 2차 인증이라 없앨 수 없지만, 언제 승인을 요청할지는 자동화할 수 있습니다. --if-expiring 은 서버에 남은 시간을 먼저 확인해서, 지정한 창보다 여유가 있으면 아무것도 하지 않고 그대로 끝납니다(exit 0). 스케줄러에 걸어두면 만료가 임박한 날에만 폰 알림이 옵니다.

tossctl auth extend --if-expiring 48h   # 48시간 이내면 연장, 아니면 no-op

macOS launchd 예시 — 매일 09:00 에 확인:

<!-- ~/Library/LaunchAgents/com.tossctl.extend.plist -->
<key>ProgramArguments</key>
<array>
  <string>/opt/homebrew/bin/tossctl</string>
  <string>auth</string><string>extend</string>
  <string>--if-expiring</string><string>48h</string>
</array>
<key>StartCalendarInterval</key>
<dict><key>Hour</key><integer>9</integer><key>Minute</key><integer>0</integer></dict>

launchctl load ~/Library/LaunchAgents/com.tossctl.extend.plist 로 등록합니다. cron 이면 0 9 * * * /opt/homebrew/bin/tossctl auth extend --if-expiring 48h.

값은 Go duration 표기입니다 — 7d 는 안 되고 168h 로 씁니다.

지원 범위

tossctl 은 토스 공식 Open API 의 조회·거래 범위를 100% 커버하고, 그 너머까지 다룹니다. 공식 Open API 문서의 모든 엔드포인트(계좌·잔고·시세·호가·체결·캔들·상하한가·매도가능수량·수수료·주문 등)에 대응하며, 추가로 수급·시장지수·AI 시그널·조건검색·관심종목 관리·거래내역 ledger·실시간 푸시·원화 소수점 주문·dry-run preview 등 39개가 공식 Open API에 없는 tossctl 고유 범위입니다.

토스증권 공식 Open API 는 현재 사전 신청자 대상으로 단계적 롤아웃 중이며, REST only 의 좁은 범위입니다 (공식 문서: https://developers.tossinvest.com/docs). 아래 표의 공식 API (예정) 칼럼은 그 문서 기준 공식이 커버하는 범위이고, tossctl 칼럼은 우리가 제공하는 범위입니다. 공식 Open API의 ✅ 행은 tossctl 도 전부 ✅ — 즉 공식 Open API 범위를 100% 커버합니다.

• ✅ 지원 · ❌ 미지원 · 🔸 부분 지원 · 🆕 최근 한 달 내 새로 추가된 기능
• 공식 API (예정) 칼럼 = 공개 문서 기준 예상 커버리지 (사전 신청자 단계적 롤아웃 — 변동 가능).
• 공식 API (예정) 가 ❌ 인 행 = tossctl 고유 범위.
• 검증 기준 버전: 아래 표·다이어그램의 공식 API 칼럼은 상단 배지에 표시된 공식 Open API 버전 기준으로 검증된 결과입니다 (그 버전·마지막 점검일은 .openapi-snapshot.json 에 기록). 전체 spec 사본을 매일 docs/migration/openapi.latest.json 에 미러링하며, 토스가 spec 을 올리면 자동 감지·알림되어 갱신됩니다.

조회 (읽기 전용) · US·KR 공통

📱 모바일 앱 전용 기능 (웹에도 UI 없음)

위 표의 대부분은 토스 웹(WTS)에 화면이 있는 기능입니다. 아래는 한 걸음 더 나아가, 토스 모바일 앱에만 화면이 있고 웹에는 UI 자체가 없는 기능입니다 — tossctl 은 웹 세션으로 호출 가능한 백엔드 API 를 통해 이것까지 조회할 수 있게 엽니다.

이 목록은 토스가 웹에 UI 를 추가하면 위 일반 조회표로 옮겨집니다. (판정 기준: 웹 라우트에 실제 화면이 뜨는지 — 주간 모니터가 추적)

거래

공식 API 도 주문 생성·정정·취소·소수점 주문(orderAmount 금액 기반 매수, 1.1.5부터 US 시장가 소수점 매도)을 제공합니다. 다만 원화(KRW) 결제 모드의 소수점 주문·dry-run preview·config 기반 안전 게이트 등 tossctl 의 거래 UX/안전장치는 우리 고유입니다.

모든 거래는 allow_live_order_actions=true도 필요합니다. 소수점 주문은 시장가(market order)로 자동 전환되며, 금액 기반입니다 (--currency-mode KRW 기본 또는 USD).

⏰ 소수점 주문 접수 시간 — 금액 주문과 소수점 수량 주문은 정규장 종료 1시간 전까지만 접수됩니다(정규장 종료 시각이 아닙니다). 그 뒤에는 서버가 422 로 거절합니다. 토스 공식 Open API 1.2.9 에서 좁혀진 규칙입니다.

US 지정가는 --currency-mode로 가격 해석을 선택합니다: KRW (기본, 서버 환율로 USD 변환) 또는 USD (입력을 USD 가격 그대로 전송). 예: order place --symbol MRVL --side buy --qty 1 --price 158.01 --currency-mode USD.

💵 지정가는 호가 단위에 맞아야 합니다 — 미국은 $1 미만이면 0.0001, $1 이상이면 0.01 단위입니다(국내는 가격대별 구간 단위, 예: 5만~20만원은 100원). 어긋나면 서버가 400 invalid-request 와 함께 가장 가까운 호가를 data.nearestPrices 로 알려줍니다. tossctl 은 가격을 그대로 전송하므로 이 검증은 서버에서 이뤄집니다.

왜 tossctl 인가 — 공식 API 는 토스 기능의 일부일 뿐

공식 Open API 는 REST 조회·주문의 기본만 제공합니다 (약 20개 엔드포인트). 반면 토스 웹앱(WTS)이 실제로 쓰는 의미있는 조회·거래 기능은 ~440개 — 온보딩·KYC·약관· 프로모션·텔레메트리 같은 무의미한 엔드포인트는 뺀 숫자입니다.

공식 Open API 는 그중 약 4%만 커버합니다. tossctl 은 나머지 범위 위에서 동작하며, 공식 Open API에 없는 기능(수급·시장지수·AI 시그널·스크리너·투자자별 순매수·어닝콜·배당 내역· 커뮤니티 랭킹·업종별 등락·뉴스 브리핑·실시간 푸시·원화 소수점 주문·dry-run preview 등)을 이미 제공하고, 남은 의미있는 범위를 계속 구현해 나갑니다.

실전 시나리오 — 공식으로 막히는 것, tossctl 로 되는 것

추상적인 "범위가 넓다"가 실제로 무슨 차이인지. 공식만으로는 ❌ → tossctl(WTS 포함)이면 ✅:

요컨대 공식은 "아는 종목을 정밀 조회하고 주문을 넣는다" 까지. tossctl 은 여기에 내 계좌의 실현손익·배당·세금 복기 + 시장 수급·지수 맥락 + 발굴·스크리닝을 더해, 단순 조회/거래 도구를 세무·수급·리서치가 붙은 종합 분석 도구로 확장합니다. 전체 매핑은 자동 라우팅 가이드 ↗ 참고.

장기적으로 tossctl 이 더 나은 이유:

• 유연성 — 토스증권에 연결하는 방법이 가장 열려 있습니다. 터미널 CLI 로, MCP 서버로 어떤 AI 에이전트(Claude Code·Codex·Gemini·Cursor·Copilot)에든, 스크립트로 — 전부 하나의 tossctl 이 처리합니다. 공식 키 없이 바로 시작하고, 연결하면 공식 경로로 자동 라우팅. 특정 앱·SDK·언어·에이전트에 묶이지 않습니다.
• 범위 — 공식 Open API는 좁은 영역을 단계적으로 천천히 엽니다. tossctl 은 웹 전체(아래 카탈로그)를 추적해 골라 구현하므로 항상 더 넓습니다.
• 속도 — 새 기능은 어느 플랫폼이든 자사 앱에서 가장 빠르게 통합되므로 늘 웹앱(WTS)에 먼저 실리고, 외부 공개용 API 는 안정적인 범위만 뒤따라 엽니다(누구의 잘못이 아니라 구조적으로 자연스러운 일). tossctl 은 주간 모니터로 신규 엔드포인트를 잡아 공식 Open API 출시를 기다리지 않고 먼저 구현합니다. 왜 공식 API가 늦는지 ↗
• 상위호환 — 공식 Open API가 커버하는 범위는 이미 100% 지원합니다 (공식 Open API가 따라와도 우리가 앞섭니다).
• 안정성(복원력) — 공식 Open API 는 엔드포인트 그룹별 초당 1~10회로 제한됩니다(계좌 조회가 초당 1회로 가장 빡빡). 빠르게 반복하면 10번 중 8번이 막혀요(실측 3개 시점). tossctl 은 막히면 곧바로 웹 세션으로 우회해 데이터를 가져오므로 사용자는 막힌 줄도 모르고 항상 성공합니다 — 자동매매·대시보드처럼 계속 불러야 할 때 차이가 큽니다. (한도 숫자는 토스 정책에 따라 바뀔 수 있어도 '막히면 우회'하는 구조는 그대로.) 공식 한도 표 + 실측 ↗

WTS 웹 API 카탈로그 (지속 추적)

웹 번들에서 모든 /api/* 엔드포인트를 추출해 구현됨 / 다음 추가 후보 / 의도적 제외로 분류하고, 추가·변경·삭제를 주간 모니터가 감지합니다. (배지 숫자는 무의미한 엔드포인트를 제외한 의미있는 범위 기준이며 카탈로그에서 자동 갱신)

• 분류 (전체 카탈로그: docs/reverse-engineering/wts-endpoints.json):
• implemented — tossctl 이 이미 제공 (각 tossctl 명령에 대응)
• candidate / priority: next — 아직 미구현, 그중 다음에 추가하면 좋을 고가치 후보를 별도 표기 (예: 가상자산 시세, 실시간 차트, 업종 내 종목 랭킹, AI 시그널 상세)
• excluded — 의도적 제외 (계좌개설·KYC·약관·프로모션·텔레메트리 등 범위 밖, 사유 기록)
• 지속 추적: 매주 웹 번들을 다시 추출해 신규/삭제/변경 엔드포인트를 감지하고 (first_seen 으로 수명주기 기록), 변동 시 알림 + 카탈로그 자동 갱신. 새 후보는 여기서 골라 구현해 나갑니다.

안전 모델

거래 기능은 기본 전부 꺼져 있습니다. 한 건의 live 주문이 broker 에 닿으려면 영속(config) 게이트와 런타임(flag) 게이트를 모두 통과해야 합니다.

flowchart TD
    A["order place / cancel / amend"] --> P{"action 토글<br/>place·cancel·amend"}
    P -->|off| X1["❌ DisabledActionError"]
    P -->|on| S{"scope 선언<br/>sell·fractional<br/>(해당 시)"}
    S -->|위반| X2["❌ DisabledActionError"]
    S -->|ok| E{"--execute"}
    E -->|없음| PV["📋 preview만 출력<br/>(confirm token 발급)"]
    E -->|있음| M{"allow_live_order_actions"}
    M -->|false| X3["❌ ErrLiveActionsDisabled"]
    M -->|true| C{"--confirm token<br/>== preview token?"}
    C -->|불일치| X4["❌ ErrConfirmMismatch"]
    C -->|일치| GO["✅ broker 로 live mutation"]

    subgraph CFG["영속 게이트 · config.json"]
        P
        S
        M
    end
    subgraph RT["런타임 게이트 · CLI flag"]
        E
        C
    end

• 영속 게이트 (config.json): place/cancel/amend 경로 토글 + sell/fractional 스코프 선언 + allow_live_order_actions 마스터 킬스위치. (시장 US/KR 은 게이트 아님 — KR 주문이 US 보다 위험하지 않으므로 동일 취급)
• 런타임 게이트 (매 실행): --execute (preview 아닌 실제 실행) + --confirm <token> (preview 에서 받은 주문별 토큰).
• 진짜 안전장치는 주문별 --confirm <token> — preview 를 봐야만 얻을 수 있어, 의도하지 않은 주문은 토큰이 어긋나 차단됩니다.

v0.5.x 간소화 히스토리: 중복이던 TTL grant 레이어(internal/permissions)를 제거하고(allow_live_order_actions 가 같은 보호 제공), 거짓 이름이던 --dangerously-skip-permissions(이제 가리킬 permissions 가 없음 + 의미도 역방향)를 은퇴시켰습니다. 기존 플래그는 한 릴리즈 동안 deprecated no-op alias 로 받아들여 스크립트/agent 호환을 유지합니다.

공식 Open API 자동 라우팅

tossctl은 웹 세션(WTS)만으로도 전부 동작합니다. 토스 공식 Open API 키를 선택적으로 연결하면 공식 Open API가 지원하는 기능은 공식 API OAuth 경로로, 나머지는 WTS로 각각 처리하는 자동 라우팅이 켜집니다. 키 없이도 모든 기능을 쓸 수 있고, 원하는 시점에 추가할 수 있습니다.

공식 Open API 와 WTS 웹 세션의 차이(인증·갱신·커버리지·안정성), IP 자동 등록, 라우팅 동작(다이어그램)은 자동 라우팅 가이드에 정리되어 있습니다.

# 공식 키 발급: https://corp.tossinvest.com/ko/open-api
tossctl init                          # 온보딩 위저드 (처음 설정 시)
tossctl openapi login                 # 공식 키 등록 (환경변수도 지원)
tossctl openapi status                # 키·토큰·허용 IP·라우팅 진단
tossctl openapi test                  # 연결 검증
tossctl account summary --backend openapi  # 공식 API 경로 강제 (선택)

키를 연결하면 CI·서버·에이전트에서 사람 개입 없이 토큰이 자동 갱신됩니다.

공식 한도는 빡빡합니다 — 공식 문서 기준 계좌 조회는 초당 1회로 가장 낮고, 빠르게 반복하면 10번 중 8번이 거절됩니다 (공식 한도 표 + 실측, 토스 정책에 따라 변동 가능). tossctl 은 막히면 자동으로 웹 세션(WTS)으로 우회하므로 반복 조회·모니터링에서도 끊김이 없습니다.

MCP 서버 (tossctl mcp)

공식 Open API 는 물론 WTS 전용 기능까지 MCP(Model Context Protocol) 서버로 노출합니다. Claude Code·Claude Desktop·Codex 등 MCP 호스트에 등록하면 에이전트가 자연어로 계좌·잔고·시세· 호가·체결·캔들(공식)과 인기 순위·수급·AI 시그널·스크리너·업종·어닝·브리핑·배당 등 WTS 전용 조회까지 다루고, 주문(매수/매도·취소·정정) 도 실행할 수 있습니다. stdin/stdout(JSON-RPC 2.0) 으로 동작하며 별도 서버·포트가 필요 없습니다.

MCP 빠른 시작 — 3단계

MCP 는 tossctl 바이너리의 한 모드(tossctl mcp)라 CLI 를 먼저 설치한 뒤 인증(공식 키·웹 세션 중 최소 하나)을 연결하고 호스트에 등록하면 끝입니다:

# 1) tossctl 설치 (macOS/Linux — Windows·Homebrew·소스 빌드는 아래 "설치" 섹션 참고)
curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh

# 2) 인증 — 하나만 있어도 시작됩니다 (없는 인증의 오퍼레이션만 비활성)
tossctl openapi login    # 공식 Open API: 공식 조회 + 주문 (발급: https://corp.tossinvest.com/ko/open-api)
tossctl auth login       # WTS 웹 세션: WTS 전용 조회(인기순위·수급·AI시그널 등)

# 3) MCP 호스트에 등록 + 연결 확인 (Claude Code 예시)
claude mcp add tossctl tossctl mcp
claude mcp list   # → "tossctl: tossctl mcp - ✔ Connected"

Claude Desktop·Codex 등 JSON 설정 방식 호스트는 아래 설정 예시를 쓰세요. 터미널에서 사람이 CLI 로 직접 쓰려면 MCP 등록 없이 tossctl auth login(웹 세션)만으로 전체 기능을 씁니다 — Quick Start 참고. 두 경로는 같은 tossctl 하나를 공유합니다.

왜 catalog 방식인가 — 상시 컨텍스트를 3개로 고정

MCP 의 고질적 비용은 툴 스키마가 모델 컨텍스트에 상시 상주한다는 점입니다. API 하나당 툴 하나로 등록하면, 그 툴의 이름·설명·파라미터 스키마 전부가 대화 내내 컨텍스트를 차지합니다. tossctl 의 API 표면은 40여 개 오퍼레이션(공식 조회 16 + 주문 3 + WTS 전용 조회 20여 + 시스템 1, 계속 증가) — 이걸 개별 툴로 노출하면 그만큼의 스키마가 항상 떠 있게 되어 토큰을 먹고, 툴 선택 노이즈(비슷한 툴 사이 오판)도 커집니다.

tossctl 은 KIS_MCP_Server 의 catalog 모드를 참조해, 앞단에 고정 3개 툴만 노출하고 나머지 오퍼레이션 전부는 필요할 때만 스키마를 꺼내오는 구조로 뒤에 둡니다:

• list_operations — 사용 가능한 오퍼레이션 목록(id·요약·write 여부) 조회, query 로 필터
• describe_operation — 특정 오퍼레이션의 파라미터 스키마를 그 순간에만 조회
• call_operation — id + 파라미터로 실제 호출

결과: 상시 컨텍스트 = 딱 3개 툴 스키마. 오퍼레이션이 40개든 100개든 상주 비용은 3으로 고정됩니다. 에이전트는 필요한 오퍼레이션을 list_operations 로 찾고 → describe_operation 으로 그때 스키마를 읽고 → call_operation 으로 호출하므로, 안 쓰는 오퍼레이션의 스키마가 컨텍스트를 차지하지 않습니다. (이 README 를 읽는 Claude Code 세션에서도 tossctl MCP 는 딱 이 3개 툴로 잡힙니다.)

MCP 가 노출하는 범위 — 조회는 공식+WTS, 쓰기는 공식 전용

MCP 는 조회를 공식 Open API + WTS 전용 기능 모두 노출하고, 주문(write)은 공식 API 경로만 씁니다. 각 오퍼레이션은 list_operations 결과에 backend로 표시됩니다 — "wts"(웹 세션 필요), "auto"(공식·웹 세션 둘 중 하나면 동작, 공식 우선 후 웹 세션 폴백), 그 외는 공식 전용.

• 조회(read) — 공식 API(계좌·시세·호가·체결·캔들 등)와 WTS 전용(인기 순위·수급·AI 시그널· 스크리너·업종·어닝·브리핑·배당 등 토스 고유 기능)을 함께 노출합니다. WTS 조회는 웹 세션이 필요하고, 없으면 해당 오퍼레이션이 tossctl auth login 안내를 돌려줍니다. 조회는 실패해도 stale read 수준이라 에이전트에 노출해도 위험이 낮습니다.
• 주문(write) — 생성·취소·정정은 항상 공식 API 경로만 사용합니다(WTS 미경유). 에이전트에 주문을 맡기는 이상 제출 경로는 토스가 공식 승인한 API 여야 안전하고 정직하기 때문입니다.
• 인증 분리. 공식 조회·주문은 공식 키(openapi login), WTS 조회는 웹 세션(auth login). 둘 중 하나만 있어도 MCP 서버는 뜨고, 각 오퍼레이션이 자기에게 필요한 인증을 확인합니다.

이로써 CLI 로만 쓰던 WTS 전용 기능을 에이전트도 MCP 로 쓸 수 있습니다.

업데이트는 자동입니다. 호스트는 tossctl mcp 라는 명령어를 저장해 세션마다 새로 실행하므로, brew upgrade tossctl-cli(또는 tossctl update)로 바이너리만 갱신하면 다음 세션·호스트 재시작 때 새 오퍼레이션이 재등록 없이 반영됩니다(catalog 는 서버 시작 시 바이너리에서 구성).

주문 실행은 CLI(tossctl order)와 동일하게 게이트됩니다: config 의 trading.* + allow_live_order_actions 토글로 켜야 하고, 기본 호출은 dry-run preview(confirm_token·경고 반환)를 돌려줍니다. 실제 제출은 execute: true + confirm: <token> 을 함께 넘겨야 합니다. 주문은 공식 API 경로만 사용(WTS 미경유) 합니다.

MCP 호스트 JSON 설정

Claude Code 는 위 MCP 빠른 시작의 claude mcp add 한 줄로 끝납니다. Claude Desktop·Codex 등 JSON 설정 방식 호스트는 다음을 설정 파일에 넣으세요(tossctl 이 PATH 에 있어야 합니다):

{
  "mcpServers": {
    "tossinvest": { "command": "tossctl", "args": ["mcp"] }
  }
}

CLI 와 MCP — 언제 무엇을 (상호 보완)

같은 tossctl 바이너리의 두 입구이고, 둘 다 AI 에이전트와 잘 맞습니다. 경쟁이 아니라 연결 방식이 다를 뿐입니다.

• AI 에이전트는 둘 다 씁니다 — 차이는 '아는 법'입니다. MCP 는 등록하면 툴로 자동 노출돼 별도 안내 없이 호출됩니다(조회는 공식+WTS, 주문은 공식). CLI 는 셸을 다루는 에이전트(Claude Code·Codex·Cursor)가 잘 실행하지만, 프롬프트에 언급하거나 스킬·AGENTS.md/CLAUDE.md 로 알려줘야 존재를 압니다 — 대신 전체 기능(실시간·WTS 쓰기 포함)에 결정적·파이프 가능합니다.
• 스크립트·cron·파이프·재현 가능한 자동화는 CLI 가 자연스럽습니다(같은 명령 = 같은 결과).
• 무엇을 쓰든 조회 데이터·주문 안전 게이트는 동일합니다: config opt-in + dry-run preview + execute/confirm 토큰.

자율 에이전트에 붙일 땐 조회 전용을 권장. config 에서 trading.* 를 끈 상태(기본값)면 MCP 는 조회만 가능하고, 주문 오퍼레이션은 호출돼도 게이트에서 막힙니다. 거래까지 열려면 사람이 명시적으로 config 를 켜야 하며, 실제 제출은 매번 execute:true + 유효한 confirm 토큰이 필요합니다.

에이전트가 CLI 로 카탈로그를 쓰는 법 — tossctl ops

MCP 의 3툴 카탈로그와 같은 오퍼레이션 레지스트리를 터미널에서도 엽니다. 타입 있는 커맨드 (tossctl account, tossctl order …)는 스스로를 열거하지 못해서, 셸로 tossctl 을 쓰는 에이전트는 --help 에 없는 기능을 알 방법이 없었습니다.

tossctl ops list --query dividend   # 오퍼레이션 찾기 (인증 불필요)
tossctl ops describe cancel_order   # 파라미터 스키마 보기 (인증 불필요)
tossctl ops call market_news --params '{"scope":"watchlist"}'

MCP 툴과 1:1로 대응합니다 — 같은 id, 같은 JSON 파라미터, 같은 JSON 출력. 한쪽에서 배운 게 그대로 다른 쪽에서 통합니다.

출력은 원시 데이터입니다 — 계좌번호·실명이 가려지지 않습니다. --output 과 무관하게 항상 JSON 이고 마스킹이 없습니다(기계용 표면이므로). 사람이 읽을 거라면 타입 있는 커맨드를 쓰세요. 주문 게이트는 동일합니다: config opt-in + execute/confirm 토큰, 없으면 dry-run preview.

설정

tossctl config init
tossctl config show

{
  "$schema": "https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/schemas/config.schema.json",
  "schema_version": 3,
  "trading": {
    "place": false,
    "sell": false,
    "fractional": false,
    "cancel": false,
    "amend": false,
    "allow_live_order_actions": false,
    "dangerous_automation": {
      "accept_fx_consent": false
    }
  },
  "update_check": {
    "enabled": true
  }
}

두 가지 유형의 토글: - 경로 게이트 (place, cancel, amend) — broker API 분기가 실제로 다른 세 동작을 각각 독립적으로 켬/끔 - 스코프 선언 (sell, fractional) — 유저가 스스로 "난 이 범주의 주문은 안 낸다"고 선언하여 실수/버그/agent 오작동 방지

v0.4.3에서 trading.grant, dangerous_automation.complete_trade_auth, dangerous_automation.accept_product_ack가, v0.5.2에서 trading.kr(비대칭 시장 게이트 — KR 주문은 US 보다 위험하지 않아 제거, 시장 대칭 취급)이 제거되었습니다. 남아있는 구 설정은 자동 무시되며, 일반 명령 실행 시 stderr 경고 1줄(24h backoff)로 안내되고 config status/doctor에서도 표시됩니다.

주문 예시

지정가 매수 (US)

tossctl config init
# config.json: place, allow_live_order_actions → true

tossctl order preview \
  --symbol TSLL --side buy --qty 1 --price 18000 --output json


tossctl order place \
  --symbol TSLL --side buy --qty 1 --price 18000 \
  --execute --confirm <token> \
  --output json

소수점 매수 (US, 금액 기반)

# config.json: place, fractional, allow_live_order_actions → true

tossctl order preview \
  --symbol TSLL --side buy --fractional --amount 1000 --qty 0 --output json

tossctl order place \
  --symbol TSLL --side buy --fractional --amount 1000 --qty 0 \
  --execute --confirm <token> \
  --output json

국내주식 매수

# config.json: place, kr, allow_live_order_actions → true

tossctl order place \
  --symbol 005930 --market kr --side buy --qty 1 --price 200000 \
  --execute --confirm <token>

매도

# config.json: sell → true (추가)

tossctl order place \
  --symbol TSLL --side sell --qty 1 --price 18000 \
  --execute --confirm <token>

다종목 시세

tossctl quote batch TSLL 005930 GOOG VOO --output table

이 프로젝트가 하지 않는 것

설치

brew tap JungHoonGhae/tossinvest-cli
brew install tossctl

irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex

git clone https://github.com/JungHoonGhae/tossinvest-cli.git
cd tossinvest-cli
make build

cd auth-helper
python3 -m pip install -e .

명령 목록

조회

tossctl account list
tossctl account summary
tossctl portfolio positions
tossctl portfolio allocation
tossctl portfolio dividends [--year YYYY] [--by-payment-date]
tossctl profit                                   # 누적 실현손익 (카테고리별)
tossctl profit summary --type sales --from 2026-01-01 --to 2026-07-25   # 기간별
tossctl profit daily --from 2026-01-01 --to 2026-07-25 --output csv      # 종목별 (세금용)
tossctl tax overseas [--year YYYY]               # 해외주식 양도소득 (세금)
tossctl tax ria                                  # RIA 절세 리포트 (모바일 앱 전용)
tossctl account interest [--year YYYY]           # 예탁금 이용료 (지급 건별)
tossctl account commission                       # 계좌 수수료 체계
tossctl order funding                            # 매수 가능 여부·필요 입금/환전액
tossctl market option-hours                      # 미국 옵션 영업일·거래시간
tossctl community boards                         # 인기 라운지 (팔로워 순)
tossctl accumulate list|status <symbol>          # 주식모으기 (모바일 앱 전용)
tossctl market investors|earnings|briefing|sectors|themes|index|ranking|signals
tossctl community rankings --type influencer|profit|followers
tossctl orders list
tossctl orders completed --market us|kr|all
tossctl order show <id>
tossctl quote get <symbol>
tossctl quote batch <symbol> [symbol...]
tossctl quote orderbook|sellable|commission <symbol>
tossctl quote crypto BTC,ETH,SOL,XRP
tossctl quote reasoning|signals <symbol>
tossctl quote options AAPL [--expiry 2026-08-05]
tossctl market filters PER PBR --nation kr
tossctl quote supply 005930 --type short --count 20
tossctl market stocks KOSPI --security-type ETF
tossctl search <이름|티커>
tossctl account receivable --currency KRW|USD
tossctl watchlist list
tossctl export positions --market us|kr|all
tossctl export orders --market us|kr|all

거래

tossctl order preview --symbol <sym> --side <buy|sell> --qty <n> --price <krw>
tossctl order preview --symbol <sym> --side buy --fractional --amount <krw> --qty 0
tossctl order place ...flags... --execute --confirm <token>
tossctl order cancel --order-id <id> --symbol <sym> ...
tossctl order amend --order-id <id> ...

order cancel·order amend·order show를 --order-id 없이 실행하면 대기/최근 주문 목록에서 직접 골라 진행할 수 있습니다. watchlist group delete·rename도 폴더 이름 없이 실행하면 목록에서 선택합니다. 파이프·비TTY에서는 프롬프트 없이 오류를 반환해 스크립트·에이전트와 안전하게 연동됩니다. 포트폴리오·시세 등 핵심 출력에는 한국식 손익 색(상승/이익=빨강, 하락/손실=파랑)이 적용되며, 파이프·비TTY·NO_COLOR·--output json|csv에서는 색 없이 동작합니다.

실시간 푸시

tossctl push listen              # SSE 구독, JSONL stdout (Ctrl+C 종료)
tossctl push listen --retry=false  # 재연결 비활성

토스 웹의 SSE 채널을 그대로 구독해 pending-order-refresh · purchase-price-refresh · share-holdings · web-push 이벤트를 JSONL로 흘립니다. 이벤트 분류와 후속 재조회 매핑은 docs/reverse-engineering/push-events.md.

시스템

tossctl version
tossctl doctor
tossctl doctor --report     # JSON 진단 번들 (이슈 첨부용, 경로 자동 redact)
tossctl config init
tossctl config show
tossctl auth login
tossctl auth status         # 세션 + Server Expiry (KST) 표시
tossctl auth extend         # 폰 푸시 승인으로 서버 측 ~7일 만료 연장
tossctl auth extend --if-expiring 48h   # 만료 임박할 때만 연장 (cron/launchd 용)
tossctl auth doctor
tossctl auth logout

공식 Open API

tossctl init                # 온보딩 위저드 (처음 설정 시)
tossctl openapi login       # 공식 키 등록 (env: TOSSCTL_OPENAPI_KEY / TOSSCTL_OPENAPI_SECRET)
tossctl openapi status      # 키·토큰·허용 IP 진단
tossctl openapi test        # 연결 검증
tossctl openapi logout      # 자격증명 파일 삭제

API 회귀 감시

tossctl monitor api           # 25개 endpoint schema probe (병렬); exit 0 통과, 1 실패
tossctl monitor api --quiet   # cron 용

본인 머신에서 본인 세션으로 16개 read-only endpoint 응답 schema 를 병렬 점검합니다. #29 같은 토스 서버측 body 계약 변경을 조기 감지할 목적. exit code 만 반환하므로 알림 채널 (Discord / Slack / ntfy / macOS / 이메일) 은 cron 라인의 || <command> 우항에서 사용자가 합성합니다. 합성 recipe: AGENTS.md. 설정 가이드: docs/operations.md.

주문 ref rollover

amend나 cancel 이후 브로커 쪽 주문 ref가 바뀔 수 있습니다.

• tossctl order show <old-id>가 local lineage cache를 통해 새 ref를 추적합니다.
• lineage cache: <config dir>/trading-lineage.json
• 같은 조건의 canceled row가 여러 개면 수동 확인이 필요합니다.

개발

make build
make test
make fmt
make tidy

FAQ

바로 주문까지 가능한가요? US/KR 지정가 매수/매도, US 소수점 매수, 당일 미체결 취소가 live 검증되어 있습니다. amend는 추가 검증이 필요합니다. 모든 거래는 config.json에서 해당 액션을 허용한 뒤에만 실행됩니다.

공식 API인가요? 아닙니다. 웹 내부 API를 재사용하는 비공식 프로젝트입니다.

왜 Playwright가 필요한가요? 로그인 세션을 브라우저 흐름으로 확보하기 위해 필요합니다. 조회/거래 로직은 Go CLI에 구현되어 있습니다.

뭔가 깨진 것 같아요. 어디서부터 확인하나요? tossctl doctor --report 를 실행하고 JSON 출력을 GitHub 이슈에 그대로 붙여주세요. 버전, OS, Chrome 버전, 세션 상태, wts-api/wts-cert-api/wts-info-api 3개 엔드포인트 실시간 응답(200/401/403), 파일 권한, 남은 임시 파일까지 한 번에 확인할 수 있어 대부분의 회귀를 빠르게 원인 파악할 수 있습니다. 홈 디렉토리 경로는 자동으로 ~로 redact되어 사용자명이 노출되지 않습니다.

문서

• docs/architecture.md
• docs/configuration.md
• docs/reverse-engineering/
• docs/trading/
• auth-helper/README.md

로컬 저장 경로

--config-dir, --session-file 플래그로 경로를 덮어쓸 수 있습니다.

Contributing

피드백을 환영합니다. 제안·버그 제보:

• GitHub에서 이슈나 PR 열기
• LinkedIn @junghoonghae
• 이메일 [email protected]

License

MIT