CLI tool
JungHoonGhae/tossinvest-cli avatar
JungHoonGhae/tossinvest-cli

tossinvest-cli: A Go CLI and MCP Server That Reaches Beyond Toss Securities' Official API

A.I. CLI MCP (AI), JSON CSV AI. A tool to handle Toss Securities through AI agents and terminals. CLI and MCP server for accounts, quotes, and orders, as well as web app-specific functions (supply/demand, AI signal, screener, dividend), and JSON/CSV structured output directly linked to AI tools and automation.

521 stars84 forksGoMIT

At a glance

What is it?
tossinvest-cli wraps Toss Securities in a Go CLI and MCP server, covering the official Open API plus web-app-only features. It is powerful but carries real legal and operational risk.
Who is it for?
Adopt tossinvest-cli if you are a developer or power user who wants scripted or AI-agent access to Toss Securities and accepts the risk of using unofficial web APIs. Do not use it if you need guaranteed compliance with Toss's terms of service or if you cannot tolerate sudden breakage from API changes.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • JungHoonGhae/tossinvest-cli521 ★ · +54
Star history
Repository2026-08-042026-11-15
JungHoonGhae/tossinvest-cli467521

54 Stars in the last 103 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What tossinvest-cli Actually Solves

Toss Securities, the South Korean brokerage, offers an official Open API, but it does not cover everything available in the web app. Features like supply/demand data, AI signals, screeners, and dividend information exist only in the web interface. tossinvest-cli is a Go program that provides a CLI and an MCP server to access both the official API and those web-only features from a terminal or an AI agent. The intended users are developers, automation engineers, and people who want to drive their Toss account from tools like Claude Code, Codex, Gemini, Cursor, or GitHub Copilot. Instead of juggling multiple scripts or reverse-engineering the web app yourself, you get one binary called `tossctl` that handles authentication, data retrieval, and order placement.

The Hybrid Architecture: Official API Plus Unofficial Web Endpoints

The README is explicit about the dual nature of the project. When you connect an official Open API key, the tool routes those functions through the supported path. But the web-app-only features use Toss's internal web APIs, which are not officially documented and are subject to change without notice. The project's warning states that using these unofficial APIs may violate Toss's terms of service and could lead to account restrictions or loss. This is not a subtle trade-off; it is the core design. The tool does not try to hide the difference. It presents a unified interface, but the underlying risk depends on which feature you call. For read-only data like quotes and account summaries, the exposure is lower. For trading actions, the stakes are higher, and the project gates those behind explicit configuration.

Getting Started: Install, Login, and the Doctor Command

Installation is a one-liner. On macOS or Linux, you run `curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh`. On Windows PowerShell, it is `irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex`. After install, the README suggests running `tossctl version` and `tossctl doctor` to verify the setup. Then you complete a browser login with `tossctl auth login`. The login requires Google Chrome and Python, which the install script configures automatically. You must also confirm the "keep this device logged in" prompt on your phone; skipping it means the session expires after about an hour of idle time. For headless environments like SSH servers or CI, there is `tossctl auth login --headless [--qr-output /tmp/toss-qr.png]`, which prints a QR URL and a confirmation letter to stderr. The README warns that the session has a roughly 7-day active expiry clock separate from the 1-year session cookie, and you can extend it with `tossctl auth extend`.

Trading Is Off by Default: The Config Gate

The project takes a cautious stance on trading. The README states that trading features are all disabled immediately after installation. You must explicitly allow each feature in `config.json` before any order can be executed. This is a deliberate safety measure, but it also means the initial setup is not just install and go. You need to edit a JSON file to enable what you need. The README also emphasizes running `tossctl order preview` before any trading mutation. That preview command is a dry-run, letting you see what would happen without placing a real order. For an AI agent, this gate is important because it prevents accidental trades from a natural language prompt. For a human user, it is a reminder that the tool can touch real money.

Session Management: The 7-Day Expiry and the Push Approval

Toss's server runs an active expiry clock of about 7 days, separate from the session cookie's 1-year Max-Age. The CLI warns on stderr when the session is within 24 hours of expiry, with a message like `session expires in ~18h; run `tossctl auth extend` to renew`. The extension requires phone approval via the Toss app, which is a second-factor step that cannot be automated away. The README offers a workaround for the timing: `tossctl auth extend --if-expiring 48h` checks the server first and does nothing if the session has more than 48 hours left. You can schedule this with a tool like launchd on macOS, so the phone notification only appears on days when an extension is actually needed. The default timeout for the extension is 120 seconds, and you can shorten it with `--timeout 60s`. This is a practical design, but it means any fully automated setup still depends on a human having the phone nearby at least once a week.

CLI vs MCP: Two Modes, Same Binary

The README presents two usage modes. For AI agents, the MCP server is the simplest path. You register it with a command like `claude mcp add tossctl tossctl mcp`, and then the agent can handle account, quote, and order tasks in natural language. For terminal use, scripts, or full access to all features including watchlist management and real-time data, the CLI is the way to go. Both modes share the same `tossctl` binary and a single login. The README points to a section on when to use which, but the truncated material does not include the full comparison. The key difference is that MCP is designed for agent integration, while the CLI gives you direct control and easier access to the full feature set. If you are building automation that does not involve an AI agent, the CLI is the more straightforward choice.

Limitations and the Wrong Tool Scenarios

The most obvious limitation is the legal risk. The README's warning is not boilerplate; it states plainly that using the web-app features may violate Toss's terms of service and that the developer accepts no responsibility for account restrictions or losses. That alone makes this the wrong tool for anyone who needs strict compliance with Toss's rules, such as institutional users or those with large account balances. Another limitation is the dependency on a phone for session extension. If you cannot approve a push notification within the 7-day window, your session dies and you must re-login. The headless login helps for initial setup, but the extension still requires phone interaction. Also, the requirement for Chrome and Python during login may be a hurdle in minimal server environments, even though the headless flag exists. Finally, the project is unofficial, so the API can change without warning, breaking scripts or agent workflows at any time.

Alternatives: The Official API and Other Unofficial Wrappers

The direct alternative is to use Toss Securities' official Open API on its own, without this tool. That approach gives you a supported, documented path for the features the official API covers, but you lose access to the web-only functions like supply/demand data and AI signals. You would also need to write your own code to handle authentication and session management. The trade-off is between safety and completeness. The official API is stable but narrower. tossinvest-cli is broader but riskier. Another alternative would be to write your own scripts against the web API, but that is exactly what this project already does, and you would inherit the same legal and stability risks without the maintained codebase. The choice comes down to whether you need the 39 web-only features listed in the README. If you do, this tool is the only ready-made option presented here. If you do not, the official API is the safer route.

Maintenance and License Implications

The project is under the MIT license, which permits commercial use, modification, and redistribution with attribution. The repository shows recent releases, with v0.43.1 pushed on 2026-08-25, indicating active maintenance. The README mentions `tossctl update` for self-updates, and Homebrew users get `brew upgrade tossctl-cli` as an automatic delegation. That suggests the project has a release pipeline and a community installation path. However, active maintenance does not change the fundamental risk: the unofficial web APIs can break at any time, and the maintainer cannot guarantee compatibility with Toss's internal changes. The license gives you the right to fork and fix it yourself, which is a real option if the project stalls. The cost of maintenance is on you: you need to keep the binary updated, monitor for breakage, and be ready to re-login or adjust config when Toss changes something. The README does not mention any paid support or enterprise plan, so you are on your own if issues arise.

Editorial conclusion

Adopt tossinvest-cli if you are a developer or power user who wants scripted or AI-agent access to Toss Securities and accepts the risk of using unofficial web APIs. Do not use it if you need guaranteed compliance with Toss's terms of service or if you cannot tolerate sudden breakage from API changes. Before any real trading, verify that your config.json explicitly enables the specific trading features you need, run `tossctl order preview` for every order, and confirm your session persistence with `tossctl auth status`. The project's own warning makes the boundary clear: official Open API keys route through supported paths, but everything else is unofficial and could lead to account restrictions.

Frequently asked questions

Is tossctl an official Toss Securities product?

No. Commands outside the official Open API reach Toss Securities web internal endpoints unofficially, which the project states may count as a terms of service violation and may change without notice. Account restrictions and losses are the user's own responsibility.

Does tossctl place live orders automatically?

No. Live trading is disabled by default and an agent stops at an order preview. A person reviews the result and confirmation token, then approves and executes the order themselves.

Can I use tossctl history commands without a network connection?

Yes. After a history sync collects holdings and transaction records, the list, search and compare history commands run offline against the saved data.

What does tossctl cover for accounts outside Toss Securities?

Only Toss Securities. Ordinary Toss banking and card spending history are explicitly out of scope.

How do I keep an agent from pulling back a huge JSON payload?

Pass a field list naming only the columns you need together with the compact flag, for example a symbol and quantity selection, instead of accepting the full structured output.

What is the experimental US options paper trading mode in tossctl?

It is still stabilising and hidden by default. Turning it on does not satisfy real options trading eligibility at Toss Securities on its own, and paper balances and orders are kept separate from live ones.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/junghoonghae-tossinvest-cli.svg)](https://hysenlabs.com/projects/junghoonghae-tossinvest-cli)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/junghoonghae-tossinvest-cli.svg)](https://hysenlabs.com/projects/junghoonghae-tossinvest-cli)

Was this useful?