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 GitHubServidor 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-mcp1 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
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_statusreports missing configuration instead of crashing. - Keeps OAuth access tokens in memory only.
- On
401 invalid-tokendata API responses, discards the cached token, requests a fresh OAuth token, and retries the original request once. auth_statusseparates token issuance from data endpoint reachability and reports whether a defaultTOSS_ACCOUNT_SEQis 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=trueplus the operation-specific gate. - Confirmation is required by default.
- Default max order amounts are
0KRW and0USD. BLOCKED_SYMBOLStakes precedence overALLOWED_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
| Name | Default | Purpose |
|---|---|---|
TOSS_API_KEY | unset | Toss Open API client id / API key. |
TOSS_SECRET_KEY | unset | Toss Open API client secret. |
TOSS_ACCOUNT_SEQ | unset | Optional default account sequence for account-scoped tools. |
ENABLE_TRADING | false | Global gate for any real order operation. |
ENABLE_ORDER_CREATE | false | Gate for real order create. |
ENABLE_ORDER_MODIFY | false | Gate for real order modify. |
ENABLE_ORDER_CANCEL | false | Gate for real order cancel. |
REQUIRE_CONFIRMATION | true | Requires exact confirmation text for real order operations. |
MAX_ORDER_KRW | 0 | Maximum allowed calculated KRW order amount. |
MAX_ORDER_USD | 0 | Maximum allowed calculated USD order amount. |
ALLOWED_SYMBOLS | unset | Optional comma-separated allow list. |
BLOCKED_SYMBOLS | unset | Optional 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_statusaccountsholdingspricesorderbooktradesprice_limitscandlesstock_infostock_warningsexchange_ratemarket_calendarorders_openorders_closedorder_detailbuying_powersellable_quantitycommissions
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/tokensucceeded.dataApiReachable: a real read-only data check againstGET /api/v1/accountssucceeded.authenticated:trueonly when both token issuance and the data endpoint check succeed.accountSeqConfigured:truewhenTOSS_ACCOUNT_SEQis set.accountSeqRequiredForAccountTools:true; account-scoped tools need either a per-callaccountSeqorTOSS_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
| Tool | Method/path | Side effect |
|---|---|---|
auth_status | POST /oauth2/token; then GET /api/v1/accounts when token issuance succeeds | Token/data reachability check only |
accounts | GET /api/v1/accounts | Read-only |
holdings | GET /api/v1/holdings | Read-only |
prices | GET /api/v1/prices | Read-only |
orderbook | GET /api/v1/orderbook | Read-only |
trades | GET /api/v1/trades | Read-only |
price_limits | GET /api/v1/price-limits | Read-only |
candles | GET /api/v1/candles | Read-only |
stock_info | GET /api/v1/stocks | Read-only |
stock_warnings | GET /api/v1/stocks/{symbol}/warnings | Read-only |
exchange_rate | GET /api/v1/exchange-rate | Read-only |
market_calendar | GET /api/v1/market-calendar/KR or GET /api/v1/market-calendar/US | Read-only |
orders_open | GET /api/v1/orders?status=OPEN | Read-only |
orders_closed | GET /api/v1/orders?status=CLOSED | Read-only |
order_detail | GET /api/v1/orders/{orderId} | Read-only |
buying_power | GET /api/v1/buying-power | Read-only |
sellable_quantity | GET /api/v1/sellable-quantity | Read-only |
commissions | GET /api/v1/commissions | Read-only |
order_validate | Local gate evaluation only | No Toss order POST |
order_create | POST /api/v1/orders | Real order only after all gates pass |
order_modify | POST /api/v1/orders/{orderId}/modify | Real order modification only after all gates pass |
order_cancel | POST /api/v1/orders/{orderId}/cancel | Real 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 fromhttps://openapi.tossinvest.com/openapi-docs/latest/openapi.json - Order create/modify/cancel: official
/api/v1/ordersPOST 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
.gitignoreexcludes.env,.env.*, logs, coverage,node_modules, and build output..npmignoreexcludes local env files, logs, coverage, internal handoff/QA notes, and local run artifacts.package.jsonfilesonly publishesdist, 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.