io.github.kcw2034/toss-invest-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.kcw2034/toss-invest-mcp what are my current holdings?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Toss Securities Open API — MCP Server
An MCP server exposing the Toss Securities Open API (20 endpoints) as LLM tools, with backend-enforced trading guardrails.
Published on the MCP Registry as
io.github.kcw2034/toss-invest-mcp and installable from PyPI via uvx toss-invest-mcp.
Built with Python + FastMCP, httpx, and pydantic.
Tools
Category | Tools |
Market data |
|
Stock info |
|
Market info |
|
Account / asset |
|
Order info |
|
Order history |
|
Order execution |
|
Related MCP server: toss-invest-mcp
Install
pip install -e .(Development extras for the test suite: pip install -e ".[dev]".)
Configure
Credentials are read from the environment (OAuth2 client-credentials grant):
export TOSS_CLIENT_ID=...
export TOSS_CLIENT_SECRET=...
export TOSS_DEFAULT_ACCOUNT=12345 # optional fallback account numberAccount-scoped tools accept an optional account_id. Resolution order:
explicit account_id → TOSS_DEFAULT_ACCOUNT → error "Account ID required.".
Trading guardrails (secure by default)
Guardrails are enforced in code, not just in tool descriptions. They are active even
if their env var is unset — a missing setting falls back to a conservative default, so a
misconfigured deployment fails closed (order rejected) rather than open. Set a cap to off
to disable it.
Var | Default | Meaning |
|
| reject KRW orders above this notional |
|
| reject USD orders above this notional |
|
| reject LIMIT orders this far from market (fat-finger guard) |
|
| notional treated as high-value (Tier-2) |
|
| require |
|
| override the API base URL |
Safety model
create_order runs a read-only pre-flight (current price; sellable quantity for sells),
then evaluates the order before placing it:
Tier 1 — absolute (non-bypassable). Order notional and price-deviation caps reject unconditionally;
confirm=truecannot override them. If a sized order's notional cannot be determined (e.g. a MARKET order with no usable market price), it is rejected — never placed uncapped.Tier 2 — confirmation-gated. Full-position liquidation (SELL ≥ sellable quantity) and high-value orders return a structured
confirmation_requiredpreview instead of executing. The agent must re-call withconfirm=trueafter the human sees the preview. Confirmed high-value orders pass the API's ownconfirmHighValueOrderflag.cancel_orderexecutes immediately — cancelling only reduces exposure.
A blocked order returns a structured result (status, reason, preview, message) and
performs no write to the API.
Run with Claude
Add to your MCP client config (e.g. Claude Desktop / Claude Code mcpServers):
{
"mcpServers": {
"toss-invest": {
"command": "python",
"args": ["-m", "toss_invest_mcp.server"],
"env": {
"TOSS_CLIENT_ID": "...",
"TOSS_CLIENT_SECRET": "...",
"TOSS_DEFAULT_ACCOUNT": "12345"
}
}
}
}Development
uv run pytest # or: pytestThe test suite mocks all HTTP with respx — it makes no live API calls.
Note: the pre-flight field extractors (
_extract_price,_extract_sellableintools/order.py) infer response field names from the documented API and should be confirmed against live responses before production trading — a wrong field name would cause an order to be rejected (fail-closed), not placed uncapped.
Available Tools
20 toolscancel_orderA
Cancel an open order (주문 취소). Executes immediately (reduces exposure).
Inputs: order_id (required), account_id.
create_orderA
PLACES A REAL ORDER with real money. Subject to backend guardrails: Tier-1 caps (notional, price deviation) reject unconditionally; Tier-2 (full liquidation, high-value) returns a preview unless confirm=true.
Inputs: side (required), symbol (required), order_type (required), price, +6 more.
get_accountsB
List the user's accounts (계좌 목록).
Inputs: no named parameters.
get_buying_powerB
Get available buying power (매수 가능 금액).
Inputs: currency (required), account_id.
get_candlesC
Get candlestick chart data (캔들 차트).
Inputs: symbol (required), interval (required), count, before, +1 more.
get_commissionsC
Get trading commissions (매매 수수료).
Inputs: account_id.
get_exchange_rateC
Get the exchange rate (환율).
Inputs: base_currency (required), quote_currency (required), date_time.
get_holdingsA
Get holdings / owned stocks (보유 주식) for an account.
Inputs: symbol, account_id.
get_market_calendar_krB
Get KR market operating calendar (국내 장 운영 정보).
Inputs: date.
get_market_calendar_usA
Get US market operating calendar (해외 장 운영 정보).
Inputs: date.
get_orderC
Get order detail (주문 상세).
Inputs: order_id (required), account_id.
get_orderbookB
Get the order book (호가) for a symbol.
Inputs: symbol (required).
get_price_limitsA
Get the upper/lower price limits (상/하한가) for a symbol.
Inputs: symbol (required).
get_pricesB
Get current prices (현재가) for one or more symbols.
Inputs: symbols (required).
get_sellable_quantityB
Get sellable quantity (판매 가능 수량) for a symbol.
Inputs: symbol (required), account_id.
get_stocksC
Get company master data / basic stock info (종목 기본 정보).
Inputs: symbols (required).
get_stock_warningsB
Get buy-caution warnings (매수 유의사항) for a symbol.
Inputs: symbol (required).
get_tradesA
Get recent executed trades (최근 체결 내역) for a symbol.
Inputs: symbol (required), count.
list_ordersC
List orders / order history (주문 목록).
Inputs: status (required), limit, cursor, symbol, +1 more.
modify_orderA
Modify an existing order (주문 정정). PLACES A REAL change.
Inputs: order_id (required), order_type (required), price, quantity, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool targets a distinct resource: market data tools for orderbook, prices, trades, candles, etc., and account/order tools for holdings, buying power, and order lifecycle. There is no overlap between get_orderbook, get_trades, get_prices, or get_order, and list_orders vs get_order are clearly list/detail.
All tools follow a consistent verb_noun pattern with verbs get, list, create, modify, and cancel. While list_orders uses 'list' instead of 'get', the pattern is predictable and uniform across the set.
20 tools is slightly above the ideal range, but the server covers two clear domains: market data (10 tools) and account/order management (10 tools). Each tool serves a distinct purpose, so the count feels justified rather than bloated.
The tool set covers the full trading lifecycle: market data retrieval, account information, and order management with create, modify, cancel, and query. No critical gaps exist; even sellable quantity and buying power are provided to support order placement.
Maintenance
Related MCP Connectors
Connect brokerage accounts to AI assistants: holdings, orders, asset lookup, and approved trading.
Unified financial infrastructure connecting AI agents directly to trade live/demo brokerage accounts, Web3 non-custodial wallets, real-time market data across equities, ETFs, crypto, forex, options, DeFi swaps, and prediction markets, institutional research feeds, and algorithmic strategy backtesters.
Guardrails for trading agents. Built-in risk management, 100+ tools for strategy R&D, 12+ venues.
Market analyst tools + AI agent: crypto, US equities, options, Korea, fundamentals, macro, backtests
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables querying Korean and US stock information, quotes, account assets, and order history via Toss Securities Open API. Optionally supports order placement with preview and confirmation safeguards.1MIT
- FlicenseBqualityDmaintenanceEnables natural language interaction with Toss Securities Open API for stock quotes, account management, and order placement via Claude.28-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to query Korean stock market data, charts, portfolio, and LS Securities account information through natural language.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language trading operations through AI assistants, supporting stocks, options, crypto, portfolio management, and real-time market data.MIT