tossinvest-cli
공식 API에 없는 30+ 기능까지, 터미널과 AI에서 쓰세요. 토스증권 비공식 CLI·MCP.
Install / Use
claude mcp add JungHoonGhae -- npx -y github:JungHoonGhae/tossinvest-cliIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Skill content
View source on GitHub[!WARNING] 이 프로젝트는 토스증권 공식 제품이 아닙니다. 공식 Open API 키를 연결하면 해당 기능은 토스가 공식 지원하는 경로로 동작하지만, 그 외 기능은 토스 웹 내부 API를 비공식적으로 사용하며 이는 토스증권 이용약관(TOS) 위반에 해당할 수 있습니다. API는 예고 없이 변경될 수 있고, 사용으로 인한 계좌 제한·손실·기타 불이익에 대해 개발자는 어떠한 책임도 지지 않습니다. 본인의 판단과 책임 하에 사용하세요.
<div align="center"> <sub><strong>WORKS WITH</strong></sub> <br /><br /> <img src="docs/assets/logos/claude.svg" height="30" alt="Claude Code" title="Claude Code" /> <picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/codex.svg" /><img src="docs/assets/logos/codex-light.svg" height="30" alt="Codex" title="Codex" /></picture> <img src="docs/assets/logos/googlegemini.svg" height="30" alt="Gemini CLI" title="Gemini CLI" /> <picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/cursor.svg" /><img src="docs/assets/logos/cursor-light.svg" height="30" alt="Cursor" title="Cursor" /></picture> <picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/githubcopilot.svg" /><img src="docs/assets/logos/githubcopilot-light.svg" height="30" alt="GitHub Copilot" title="GitHub Copilot" /></picture> <img src="docs/assets/logos/opencode.svg" height="30" alt="OpenCode" title="OpenCode" /> <img src="docs/assets/logos/qwen.svg" height="30" alt="Qwen Code" title="Qwen Code" /> <img src="docs/assets/logos/deepseek.svg" height="30" alt="DeepSeek" title="DeepSeek" /> <img src="docs/assets/logos/mistralai.svg" height="30" alt="Mistral" title="Mistral" /> <picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/moonshotai.svg" /><img src="docs/assets/logos/moonshotai-light.svg" height="30" alt="Kimi CLI" title="Kimi CLI" /></picture> <img src="docs/assets/logos/openclaw.svg" height="30" alt="OpenClaw" title="OpenClaw" /> </div>[!IMPORTANT] 거래 기능은 설치 직후 모두 꺼져 있습니다.
config.json에서 기능별로 직접 허용해야만 실행됩니다.
<p align="center"> <a href="https://www.star-history.com/#JungHoonGhae/tossinvest-cli&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/star-history/star-history-dark.svg" /> <source media="(prefers-color-scheme: light)" srcset="docs/assets/star-history/star-history-light.svg" /> <img alt="Star History Chart" src="docs/assets/star-history/star-history-light.svg" width="600" /> </picture> </a> </p> <p align="center"> <a href="https://www.star-history.com/?repos=JungHoonGhae%2Ftossinvest-cli"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=JungHoonGhae/tossinvest-cli&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=JungHoonGhae/tossinvest-cli" /> <img alt="Star History Rank" src="https://api.star-history.com/badge?repo=JungHoonGhae/tossinvest-cli" /> </picture> </a> </p>
후원
<p align="center"> <a href="https://github.com/sponsors/JungHoonGhae"><img src="docs/assets/badges/sponsor.svg" height="46" alt="Become a sponsor" /></a> </p> <!-- sponsors:start --> <p align="center"> <a href="https://github.com/sponsors/JungHoonGhae" title="비공개 후원자 / private sponsor"><img src="docs/assets/sponsors/anonymous.svg" width="56" height="56" alt="private sponsor" /></a> </p> <p align="center"><sub>현재 <strong>1</strong>분이 제 오픈소스 작업을 후원하고 있습니다 (일회성 포함). 후원은 tossinvest-cli 를 포함한 제 작업 전반에 쓰입니다.</sub></p> <!-- sponsors:end -->빠른 시작
어떻게 쓸지에 따라 고르세요.
- 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로 씁니다.
지원 범위
<p align="center"> <img src="docs/assets/api-comparison.svg" alt="tossctl vs 공식 Open API(예정) 커버리지 비교 — tossctl 이 상위집합" width="840" /> </p>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 공통
| 기능 | 커맨드 | 공식 API (예정) | tossctl |
|------|--------|:--:|:--:|
| 계좌 목록 / 요약 | account list, account summary | ✅ | ✅ |
| 포트폴리오 | portfolio positions, portfolio allocation (US: USD 병기) | ✅ | ✅ |
| 체결 내역 (틱) | quote trades <symbol> --count N | ✅ | ✅ |
| 호가 (bid/ask 10단계) | quote orderbook <symbol> (매도·매수 잔량) | ✅ | ✅ |
| 상/하한가 | quote limits <symbol> (KR) | ✅ | ✅ |
| 매수 유의사항 | quote warnings <symbol> (정리매매·투자경고·VI 등) | ✅ | ✅ |
| 장 운영 시간 | market hours (오늘 + 휴장 시 다음 영업일) | ✅ | ✅ |
| 환율 | market fx (달러 환율·달러 인덱스) | ✅ | ✅ |
| 매도가능수량 | quote sellable <symbol> (보유 종목 매도가능 주수) | ✅ | ✅ |
| 수수료 / 거래세율 | quote commission <symbol> (수수료율·거래세율) | ✅ | ✅ |
| 미체결 / 체결 / 단건 주문 | orders list, orders completed, order show <id> | ✅ | ✅ |
| 시세 | quote get <symbol> (OHLC·52주 고저·시총·거래대금·체결강도) | 🔸 (체결강도·52주 등 제외) | ✅ |
| 캔들 차트 | quote chart --interval 1m\|3m\|5m\|10m\|15m\|30m\|60m | 🔸 (1분·일봉만) | ✅ |
| 멀티 시세 / 실시간 갱신 | quote batch <sym>[,sym,...] (--chart·--live) | ❌ | ✅ |
| 🆕 가상자산 시세 + 김프 | quote crypto BTC,ETH,SOL,XRP (OHLC·52주·김치 프리미엄) | ❌ | ✅ |
| 🆕 종목 수급 (5종) | quote supply <symbol> --type investor\|short\|credit\|lending\|program | ✅ | ✅ |
| 🆕 스크리너 필터 값 범위 | `market filters PER PBR --nation kr\
Truncated for display — read the full file on GitHub.
Related Skills
caveman
107.2k🪨 why use many token when few token do trick. Viral skill + proxy for coding agents that cuts 65% of tokens by talking like a caveman.
claude-mem
94.4kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
84.4kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
83.6kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
