tossinvest-openapi-mcp

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

This package is an independent developer tool and is not affiliated with, endorsed by, or sponsored by Toss Securities.

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.

• On 401 invalid-token data API responses, discards the cached token, requests a fresh OAuth token, and retries the original request once.

• auth_status separates token issuance from data endpoint reachability and reports whether a default TOSS_ACCOUNT_SEQ is configured.

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

• Trading is disabled by default.

• v0.2 workflow tools are safety-first and preview-based: portfolio_snapshot → pre_trade_check → order_preview → approval → order_execute → order_status_summary.

• order_preview stores preview contracts in memory only and never calls Toss order POST endpoints.

• order_execute is intentionally fast: it rechecks only preview/confirmation/hash/env/delegated-authority gates, submits at most one order POST, and reports timeout/network ambiguity as unknown_execution_state for reconciliation before any manual retry.

• 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: tossinvest-openapi-mcp

Install and run

This repository is currently distributed from GitHub source only. It has not been published to npm under an EthanKlocked-owned package.

Important: the unscoped npm name tossinvest-openapi-mcp is already used by a different npm package, so do not install or run that package expecting this repository's code.

Clone this repository, then install and build locally:

git clone https://github.com/EthanKlocked/tossinvest-openapi-mcp.git
cd tossinvest-openapi-mcp
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

Use the local cloned path:

{
  "mcpServers": {
    "tossinvest": {
      "command": "node",
      "args": ["/absolute/path/to/cloned/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}"
      }
    }
  }
}

If this project is later published to npm, use a package name owned by the maintainer, such as @ethanklocked/tossinvest-openapi-mcp, rather than the already-taken unscoped name.

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

Workflow tools:

• portfolio_snapshot — reads holdings, KRW/USD buying power, open orders, calculable position weights, account/accountSeq state, warning flags, and partial failures. Position weights use a KRW-converted, cash-inclusive denominator (holdings + KRW/USD cash buying power); when cashStatus is partial, omitted cash currencies are listed in omittedCashCurrencies.

• pre_trade_check — separate read/check layer for candidate orders; returns canProceedDryRun, realOrderBlockedByDefault, checks, warnings, blockers, missing, estimate, and dataFreshness.

• order_preview — creates an in-memory preview contract; returns previewId, requestHash, ttlSeconds, expiresAt, exact confirmationText, estimated amount/fee/cash/quantity checks, gate status, risk flags, and calculability notes. It never calls order POST endpoints. Default TTL: 90 seconds; max accepted TTL: 300 seconds.

• order_execute — fast preview-based submission; requires previewId, matching requestHash, exact confirmation (I approve this exact Toss order preview), unexpired preview, env gates, and optional delegated-authority bounds. It does not run pre_trade_check in the hot path and does not add automatic order POST retry.

• order_status_summary — read-only reconciliation summary for open/recently closed orders, state counts, filled/partial/canceled/rejected/replace-related states when present, and caveats for disappeared/replaced orders.

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. When ALLOWED_SYMBOLS or BLOCKED_SYMBOLS is configured, real cancellation also requires caller-supplied request.symbol so local symbol policy can be evaluated before the POST. The server does not fetch order details before cancel because this would add a second API dependency and the official detail payload shape should be confirmed by users with live credentials before relying on it for safety.

Auth status and account selection

auth_status intentionally separates OAuth token issuance from actual data API reachability:

• configured: required credential environment variables are present.

• tokenAvailable: POST /oauth2/token succeeded.

• dataApiReachable: a real read-only data check against GET /api/v1/accounts succeeded.

• authenticated: true only when both token issuance and the data endpoint check succeed.

• accountSeqConfigured: true when TOSS_ACCOUNT_SEQ is set.

• accountSeqRequiredForAccountTools: true; account-scoped tools need either a per-call accountSeq or TOSS_ACCOUNT_SEQ.

Most market-data tools such as prices, orderbook, trades, and stock_info do not require accountSeq. Account-scoped tools such as holdings, orders_open, orders_closed, order_detail, buying_power, sellable_quantity, commissions, and real/dry-run order tools require accountSeq via the tool arguments or TOSS_ACCOUNT_SEQ.

Endpoint mapping

v0.2 workflow examples

Recommended safety-first flow:

portfolio_snapshot → pre_trade_check → order_preview → user/delegated approval → order_execute → order_status_summary

Market calendar checks are routed by request market:

• currency=KRW or a six-digit Korean stock symbol uses market_calendar(KR).

• US tickers / currency=USD use market_calendar(US).

• US non-business days are detected from the official calendar shape when result.today.dayMarket, preMarket, regularMarket, and afterMarket are all null.

• KR non-business days are detected when result.today.integrated is null.

• In those cases pre_trade_check and order_preview return a market_closed_non_business_day blocker with market, date, and nextBusinessDay; they do not report market_open_unknown in missing.

portfolio_snapshot example:

{
  "accountSeq": 1,
  "currencies": ["KRW", "USD"],
  "limit": 50
}

pre_trade_check example. This is a separate read/check tool and is intentionally not forced into order_execute's hot path:

{
  "accountSeq": 1,
  "request": {
    "symbol": "005930",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": "1",
    "price": "70000",
    "currency": "KRW"
  },
  "delegatedAuthority": {
    "remainingAmount": 100000,
    "expiresAt": "2026-07-05T15:00:00.000Z"
  }
}

order_preview example. It never calls Toss order POST endpoints and returns previewId, requestHash, TTL, and exact confirmation text:

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

order_execute example. Copy the previewId, requestHash, and exact confirmationText from the preview response:

{
  "previewId": "preview_...",
  "requestHash": "<sha256-from-preview>",
  "confirmation": "I approve this exact Toss order preview"
}

If an order POST times out or returns an ambiguous network failure, order_execute returns status: "unknown_execution_state" and directs callers to reconcile with order_status_summary/order_detail before any manual retry. The server does not automatically retry order POSTs.

order_status_summary example:

{
  "accountSeq": 1,
  "symbol": "005930",
  "limit": 50
}

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.

Opt-in read-only integration smoke test

After configuring your own Toss credentials locally, you can run a safe read-only smoke test:

TOSS_API_KEY=... TOSS_SECRET_KEY=... npm run smoke:readonly

Optional account-scoped checks can use TOSS_ACCOUNT_SEQ, but the default smoke path only calls read-only tools that do not create, modify, or cancel orders: auth_status, accounts, and market_calendar. If TOSS_API_KEY or TOSS_SECRET_KEY is missing, the command exits successfully with a SKIP message and makes no Toss API request. Output is passed through the same redaction helpers used by the MCP server.

Timeout/retry policy

This server applies a configurable request timeout to OAuth, read-only calls, and order calls. It intentionally does not add broad automatic retries: read-only retry policy should be based on observed Toss API behavior, and order POST retries are disabled unless official idempotency guarantees are documented. The only automatic retry remains the existing one-time token refresh/retry for a 401 invalid-token response.

Release checklist

Before publishing or tagging a release:

1. Verify package ownership and name availability; do not publish the unscoped tossinvest-openapi-mcp name.

2. Run npm test, npm run lint, npm run audit:prod, and npm pack --dry-run.

3. Confirm the dry-run tarball includes only runtime files (dist/ JavaScript/declarations without source maps), scripts/smoke-readonly.mjs, README.md, LICENSE, .env.example, and package metadata.

4. Re-scan docs for secrets, account numbers, local paths, private workflow notes, or investment advice/automation claims.

5. Publish only after explicit maintainer approval.

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.