How do I use io.github.kcw2034/toss-invest-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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	`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: Alpaca MCP Server

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.