Io.Github.Kcw2034/Toss Invest

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

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.

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.