Skip to main content
Glama
io.github.kcw2034/toss-invest-mcp

io.github.kcw2034/toss-invest-mcp

by kcw2034

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

get_orderbook, get_prices, get_trades, get_price_limits, get_candles

Stock info

get_stocks, get_stock_warnings

Market info

get_exchange_rate, get_market_calendar_kr, get_market_calendar_us

Account / asset

get_accounts, get_holdings

Order info

get_buying_power, get_sellable_quantity, get_commissions

Order history

list_orders, get_order

Order execution

create_order, modify_order, cancel_order

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 number

Account-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

TOSS_MAX_ORDER_NOTIONAL_KRW

1000000

reject KRW orders above this notional

TOSS_MAX_ORDER_NOTIONAL_USD

1000

reject USD orders above this notional

TOSS_MAX_PRICE_DEVIATION_PCT

5.0

reject LIMIT orders this far from market (fat-finger guard)

TOSS_HIGH_VALUE_NOTIONAL

100000000

notional treated as high-value (Tier-2)

TOSS_REQUIRE_CONFIRM_HIGH_RISK

true

require confirm=true for full liquidation / high-value orders

TOSS_BASE_URL

https://openapi.tossinvest.com

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=true cannot 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_required preview instead of executing. The agent must re-call with confirm=true after the human sees the preview. Confirmed high-value orders pass the API's own confirmHighValueOrder flag.

  • cancel_order executes 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: pytest

The test suite mocks all HTTP with respx — it makes no live API calls.

Note: the pre-flight field extractors (_extract_price, _extract_sellable in tools/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 tools
cancel_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

    A3.6/5.0

    Scored across 20 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      Enables natural language interaction with Toss Securities Open API for stock quotes, account management, and order placement via Claude.
      28
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to query Korean stock market data, charts, portfolio, and LS Securities account information through natural language.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language trading operations through AI assistants, supporting stocks, options, crypto, portfolio management, and real-time market data.
      MIT