tossinvest-openapi-mcp

Safe-by-default local stdio MCP server for the official Toss Securities / 토스증권 Open API.

This package is designed for developers who want read-only account, market, and order data in an MCP client, with optional order operations protected by multiple explicit safety gates.

Safety defaults

• Uses only the official Toss Open API server: https://openapi.tossinvest.com

• Starts without credentials; auth_status reports missing configuration instead of crashing.

• Keeps OAuth access tokens in memory only.

• Redacts API keys, secrets, bearer tokens, account headers, and account numbers from tool output/errors.

• Trading is disabled by default.

• Order tools default to dryRun=true.

• Real create/modify/cancel operations require ENABLE_TRADING=true plus the operation-specific gate.

• Confirmation is required by default.

• Default max order amounts are 0 KRW and 0 USD.

• BLOCKED_SYMBOLS takes precedence over ALLOWED_SYMBOLS.

Related MCP server: kiwoom-mcp

Install and run

npm install
npm run build
npm test

Run locally:

TOSS_API_KEY=... TOSS_SECRET_KEY=... node dist/index.js

Do not put real secrets in committed files. Prefer passing env vars from your local shell or MCP client secret manager.

MCP client configuration example

{
  "mcpServers": {
    "tossinvest": {
      "command": "node",
      "args": ["/absolute/path/to/tossinvest-openapi-mcp/dist/index.js"],
      "env": {
        "TOSS_API_KEY": "${TOSS_API_KEY}",
        "TOSS_SECRET_KEY": "${TOSS_SECRET_KEY}",
        "TOSS_ACCOUNT_SEQ": "${TOSS_ACCOUNT_SEQ}"
      }
    }
  }
}

Environment variables

Confirmation text for real order operations:

I understand this may place a real Toss Securities order

Tools

Read-only tools:

• auth_status

• accounts

• holdings

• prices

• orderbook

• trades

• price_limits

• candles

• stock_info

• stock_warnings

• exchange_rate

• market_calendar

• orders_open

• orders_closed

• order_detail

• buying_power

• sellable_quantity

• commissions

Trading tools:

• order_validate — checks local gates only and never calls Toss order POST endpoints.

• order_create — defaults to dry-run; real execution requires all create gates.

• order_modify — defaults to dry-run; real execution requires all modify gates.

• order_cancel — defaults to dry-run; real execution requires all cancel gates.

Endpoint mapping

Trading safety examples

Dry-run validation:

{
  "request": {
    "symbol": "005930",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": "1",
    "price": "70000",
    "currency": "KRW"
  }
}

Real create requires all of the following:

ENABLE_TRADING=true
ENABLE_ORDER_CREATE=true
REQUIRE_CONFIRMATION=true
MAX_ORDER_KRW=100000
ALLOWED_SYMBOLS=005930

And the tool call must include:

{
  "dryRun": false,
  "confirmation": "I understand this may place a real Toss Securities order",
  "request": {
    "symbol": "005930",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": "1",
    "price": "70000",
    "currency": "KRW"
  }
}

Official endpoint mapping

The implementation is intentionally thin and maps tools to official Toss Open API paths:

• OAuth: POST /oauth2/token

• Market/account/order data: /api/v1/... paths from https://openapi.tossinvest.com/openapi-docs/latest/openapi.json

• Order create/modify/cancel: official /api/v1/orders POST paths only, guarded locally before any POST is attempted.

Development

npm install
npm test
npm run lint
npm run audit:prod

The required test suite uses Node's built-in test runner and mocked fetch calls. It does not require real Toss credentials and does not call live order endpoints.

Publication hygiene

• .gitignore excludes .env, .env.*, logs, coverage, node_modules, and build output.

• .npmignore excludes local env files, logs, coverage, internal handoff/QA notes, and local run artifacts.

• package.json files only publishes dist, public docs, .env.example, and changelog/security/license files.

Disclaimer

This software is not investment advice and does not implement trading strategy, rebalancing, optimization, or automated trading loops. Order tools can place real financial orders only when explicitly enabled and used with valid Toss credentials; use at your own risk.