convez.ai
MCP ServerFinanceiroAvançado
EthanKlocked

Toss Invest OpenAPI MCP Server

EthanKlocked/tossinvest-openapi-mcp

MCP server seguro para Toss Securities com gates de trading e proteções por padrão

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP seguro por padrão para a API aberta da Toss Securities, oferecendo ferramentas de leitura de mercado e conta com operações de ordem protegidas por múltiplas camadas de segurança. Ideal para desenvolvedores que precisam integrar dados de investimentos com controle fino sobre operações de trading.

Instalação

$npx convez-ai EthanKlocked/tossinvest-openapi-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
—
Issues abertas
2
Contribuidores
1

Casos de uso

  • Integrar dados de mercado e conta da Toss em agentes Claude
  • Construir sistemas de análise de portfólio com acesso read-only seguro
  • Implementar automação de trading com múltiplas camadas de confirmação

Veredito

MCP bem arquitetado com ênfase genuína em segurança — os padrões conservadores (trading desabilitado, dry-run por padrão, gates explícitos) refletem bom julgamento. Requer credenciais e setup local, adequado para devs que trabalham com investimentos.

README

A tradução para o português deste README ainda está na fila.

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.
  • 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.

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

NameDefaultPurpose
TOSS_API_KEYunsetToss Open API client id / API key.
TOSS_SECRET_KEYunsetToss Open API client secret.
TOSS_ACCOUNT_SEQunsetOptional default account sequence for account-scoped tools.
ENABLE_TRADINGfalseGlobal gate for any real order operation.
ENABLE_ORDER_CREATEfalseGate for real order create.
ENABLE_ORDER_MODIFYfalseGate for real order modify.
ENABLE_ORDER_CANCELfalseGate for real order cancel.
REQUIRE_CONFIRMATIONtrueRequires exact confirmation text for real order operations.
MAX_ORDER_KRW0Maximum allowed calculated KRW order amount.
MAX_ORDER_USD0Maximum allowed calculated USD order amount.
ALLOWED_SYMBOLSunsetOptional comma-separated allow list.
BLOCKED_SYMBOLSunsetOptional comma-separated block list; always wins over allow list.

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.

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

ToolMethod/pathSide effect
auth_statusPOST /oauth2/token; then GET /api/v1/accounts when token issuance succeedsToken/data reachability check only
accountsGET /api/v1/accountsRead-only
holdingsGET /api/v1/holdingsRead-only
pricesGET /api/v1/pricesRead-only
orderbookGET /api/v1/orderbookRead-only
tradesGET /api/v1/tradesRead-only
price_limitsGET /api/v1/price-limitsRead-only
candlesGET /api/v1/candlesRead-only
stock_infoGET /api/v1/stocksRead-only
stock_warningsGET /api/v1/stocks/{symbol}/warningsRead-only
exchange_rateGET /api/v1/exchange-rateRead-only
market_calendarGET /api/v1/market-calendar/KR or GET /api/v1/market-calendar/USRead-only
orders_openGET /api/v1/orders?status=OPENRead-only
orders_closedGET /api/v1/orders?status=CLOSEDRead-only
order_detailGET /api/v1/orders/{orderId}Read-only
buying_powerGET /api/v1/buying-powerRead-only
sellable_quantityGET /api/v1/sellable-quantityRead-only
commissionsGET /api/v1/commissionsRead-only
order_validateLocal gate evaluation onlyNo Toss order POST
order_createPOST /api/v1/ordersReal order only after all gates pass
order_modifyPOST /api/v1/orders/{orderId}/modifyReal order modification only after all gates pass
order_cancelPOST /api/v1/orders/{orderId}/cancelReal order cancellation only after all gates pass

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.

Ver o original no GitHub

Bom para

Relacionados