tossinvest-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tossinvest-mcp show me my current portfolio holdings"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tossinvest-mcp-server
An MCP server for the Toss Securities (토스증권) Open API — Korean (KRX) and US market data, portfolio holdings, order management and price-triggered conditional orders.
28 tools cover every documented endpoint of the Open API (v1.2.5).
Requirements
Node.js 18+
Toss Securities Open API credentials: log into the Toss Securities WTS, go to 설정 › Open API, issue a
client_id/client_secret, and register the calling IP under 허용 IP 관리. Calls from an unregistered IP are rejected with403 edge-blocked.
Related MCP server: tossinvest-openapi-mcp
Install
npm install && npm run buildConfiguration
Variable | Required | Purpose |
| yes¹ | OAuth 2.0 client id |
| yes¹ | OAuth 2.0 client secret |
| no | Pre-issued access token; bypasses the client-credentials flow |
| no | Default |
| no |
|
| no |
|
| no | HTTP port when |
¹ Required unless TOSSINVEST_ACCESS_TOKEN is set.
Tokens are issued, cached and refreshed automatically. Toss keeps exactly one valid token per client, so the server collapses concurrent refreshes into a single request and retries once on a rejected token.
Claude Desktop / Claude Code
{
"mcpServers": {
"tossinvest": {
"command": "node",
"args": ["/absolute/path/to/tossinvest-mcp/dist/index.js"],
"env": {
"TOSSINVEST_CLIENT_ID": "c_...",
"TOSSINVEST_CLIENT_SECRET": "...",
"TOSSINVEST_READ_ONLY": "true"
}
}
}
}Remote / self-hosted (streamable HTTP)
Serves stateless JSON-RPC at POST /mcp, plus an unauthenticated GET /health for container probes.
Bearer authentication is mandatory in this mode — the process refuses to start without MCP_AUTH_TOKEN, because the endpoint exposes credentials that can read your account and place orders. Set MCP_ALLOW_ANONYMOUS=true to override, only when the port is genuinely unreachable from outside a trusted network.
MCP_AUTH_TOKEN=$(openssl rand -hex 32) TRANSPORT=http npm startVariable | Purpose |
| Bearer token clients must present. Minimum 16 chars; compared in constant time |
|
|
| Bind address, default |
| Port the process listens on, default |
| Compose only: host port published on the NAS, default |
Docker / NAS
cp .env.example .env # fill in credentials + MCP_AUTH_TOKEN, then:
docker compose up -d --buildCI publishes a multi-arch image (linux/amd64 + linux/arm64) to GHCR on every push to main. To use it instead of building on the NAS, drop the build: line from docker-compose.yml and set:
image: ghcr.io/meteoroh/tossinvest-mcp:latestThe bundled docker-compose.yml defaults to the conservative setup: read-only mode on, port published to 127.0.0.1 only, container runs unprivileged with a read-only root filesystem and all capabilities dropped. Reach it over a VPN (Tailscale/WireGuard), a Cloudflare Tunnel, or a TLS-terminating reverse proxy rather than publishing it to the internet.
Note that the Toss API allow-lists by IP, so the NAS's public IP must be registered under 허용 IP 관리 — a different IP than your laptop's. Fronting the server with a tunnel or proxy does not change this: outbound calls to Toss still leave from the NAS.
Nginx Proxy Manager
For Portainer stacks or Synology Container Manager — which accept only one file — use the flattened, self-contained examples/docker-compose.npm.yml. It pulls the published image, so the NAS never compiles anything.
Otherwise, docker-compose.npm.yml overlays the networking needed to sit behind an existing NPM instance.
docker compose -f docker-compose.yml -f docker-compose.npm.yml up -d --buildThe base file publishes on loopback, which NPM cannot reach — inside NPM's container, 127.0.0.1 is NPM itself. The overlay drops the host port entirely and joins NPM's network instead, so NPM reaches the server by container name on its internal port 3000 (host port collisions are irrelevant here, since nothing is published). Find that network with:
docker inspect <npm-container> -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}}{{"\n"}}{{end}}'and set it in .env as NPM_NETWORK (commonly npm_default).
Then in Proxy Hosts › Add Proxy Host:
Field | Value |
Domain Names |
|
Scheme |
|
Forward Hostname |
|
Forward Port |
|
Block Common Exploits | on |
SSL | Let's Encrypt cert, Force SSL on |
Two things to get right:
Do not attach an Access List. NPM's Access Lists use HTTP Basic Auth, which occupies the same
Authorizationheader this server reads its bearer token from. NPM overwrites the header and every request fails with 401. UseMCP_AUTH_TOKENas the gate instead — or, if you want a second layer, add it as a custom header check in the Advanced tab rather than an Access List.Cloudflare SSL/TLS mode must be Full (strict) if the DNS record is proxied (orange cloud).
Flexiblewould leave the Cloudflare→NAS hop unencrypted, which is where your bearer token travels. For the Let's Encrypt cert, use NPM's DNS challenge with a Cloudflare API token — HTTP-01 validation is unreliable through the Cloudflare proxy.
Unlike a tunnel, this needs ports 80 and 443 forwarded to the NAS.
Cloudflare Tunnel (alternative)
docker-compose.cloudflared.yml overlays a cloudflared sidecar, giving you a hostname on your own domain with no inbound port, no port forwarding and no certificate to manage. It also works behind CGNAT.
Zero Trust dashboard → Networks › Tunnels › Create a tunnel (Cloudflared). Copy the token into
.envasTUNNEL_TOKEN.Add a Public Hostname on the tunnel: subdomain
mcp, your domain, serviceHTTP→tossinvest-mcp:3000.Start both containers:
docker compose -f docker-compose.yml -f docker-compose.cloudflared.yml up -d --buildThe overlay clears the host port mapping — cloudflared reaches the server over the internal compose network, so nothing is exposed on the NAS at all.
Add Cloudflare Access in front. Zero Trust → Access › Applications › Self-hosted, covering mcp.yourdomain.com, with a service token policy. Requests without a valid service token are rejected at Cloudflare's edge and never reach your NAS. Clients then send three headers:
{
"mcpServers": {
"tossinvest": {
"url": "https://mcp.yourdomain.com/mcp",
"headers": {
"CF-Access-Client-Id": "....access",
"CF-Access-Client-Secret": "...",
"Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
}
}
}
}MCP_AUTH_TOKEN stays in place as the origin-level gate, so a Cloudflare misconfiguration alone does not expose the server.
If you enable Access, exclude /health from the policy (or drop your container health check) — otherwise the probe gets a login redirect instead of a 200.
Connecting a client
claude mcp add --transport http tossinvest https://your-host/mcp --header "Authorization: Bearer $MCP_AUTH_TOKEN"Cursor and other mcp.json-based clients take the equivalent:
{
"mcpServers": {
"tossinvest": {
"url": "https://your-host/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}For clients that only speak stdio, bridge with npx mcp-remote https://your-host/mcp --header "Authorization: Bearer YOUR_TOKEN".
Tools
Market data — no account required
Tool | Purpose |
| Last traded price, up to 200 symbols per call |
| Bid/ask ladder for one symbol |
| Today's most recent executions |
| Daily upper/lower price band |
| OHLCV history, 1-minute or daily, max 200 bars |
| Symbol master data: names, market, type, status, shares outstanding |
| Active trading warnings and VI flags |
| KRW ↔ USD rate |
| KR or US session hours for 3 business days |
| Top-100 by traded value, volume or price change |
| KOSPI/KOSDAQ levels, Korean treasury yields |
| Index / bond-yield OHLCV history |
| KRX buy/sell value by investor type |
Account and portfolio
Tool | Purpose |
| Accounts and their |
| Positions with valuation and P/L |
| Cash available to buy with |
| Shares available to sell |
| Per-market commission rates |
Orders
Tool | Purpose | Mutating |
| Working or finished orders | |
| One order with its fill detail | |
| Place a buy or sell order | ✅ |
| Change price / quantity | ✅ |
| Cancel a working order | ✅ |
Conditional orders
Tool | Purpose | Mutating |
| Active or finished conditional orders | |
| One conditional order in detail | |
| Register a SINGLE / OCO / OTO trigger | ✅ |
| Replace a conditional order | ✅ |
| Stop watching | ✅ |
Safety
The five mutating tools place, change and cancel real orders with real money.
Set
TOSSINVEST_READ_ONLY=trueto drop them entirely — the server then exposes 22 read-only tools and cannot trade at all. This is the recommended default for research and analysis.They are annotated
readOnlyHint: false, destructiveHint: true, so MCP clients that gate destructive tools will prompt before running them.tossinvest_create_orderandtossinvest_create_conditional_orderacceptclient_order_idas an idempotency key. Pass one: a retried request then returns the original order instead of filling twice.A successful create means the order was accepted, not filled. Read the outcome with
tossinvest_get_order.
Conventions
Symbols — KRX uses 6 digits (
005930), US uses tickers (AAPL). There is no name-to-symbol search endpoint.Numbers — prices, quantities and amounts are decimal strings, so precision survives round-tripping. Don't reformat them before sending them back.
Currencies — KRW and USD amounts are always reported separately and never summed. Convert with
tossinvest_get_exchange_ratewhen one figure is wanted.Time — all timestamps are KST (+09:00), including US session times.
Output — every tool takes
response_format:markdown(default, compact) orjson(complete payload). Structured content is returned either way. Oversized list responses are shortened with an explicittruncation_message.
Rate limits
Limits are per client × API group and low — the account group allows 1 request per second. The client retries 429 and 5xx automatically, honouring Retry-After with exponential backoff and jitter (3 attempts). Batch symbols instead of looping; one call with 200 symbols beats 200 calls.
Errors
Failures come back as readable text with a recovery step rather than a stack trace:
Error 422 (insufficient-buying-power): 주문 가능 금액이 부족합니다.
Next step: Not enough cash. Check tossinvest_get_buying_power for the available amount.
Request id: 01HXYZABCDEFG123456789 (include this when contacting Toss support)Development
npm run dev # watch mode
npm run typecheck # strict type check
npm test # build + output schema validation + stdio protocol smoke testnpm test makes one deliberately unauthenticated API call to confirm the error path renders correctly; it never places orders.
License
MIT. Not affiliated with or endorsed by Toss Securities. Using the trading tools is at your own risk.
Available Tools
28 toolstossinvest_cancel_conditional_orderCancel a conditional orderADestructiveIdempotent
Cancel a standing conditional order so it stops watching the price. This cancels a REAL standing order — confirm with the user first.
Args:
conditional_order_id (string): the conditional order to cancel.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, conditionalOrderId, operation: 'canceled' }.
This only removes the watcher. Any real order already placed by a fired condition is untouched — cancel that separately with tossinvest_cancel_order.
Errors: 404 conditional-order-not-found.
Inputs: conditional_order_id (required), account_seq, response_format. Returns: note, operation, accountSeq, clientOrderId, +1 more
tossinvest_cancel_orderCancel an open orderADestructiveIdempotent
Cancel a working order. This cancels a REAL order — confirm with the user first.
Args:
order_id (string): the order to cancel. Get it from tossinvest_list_orders with status='OPEN'.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, orderId, operation: 'canceled' }.
A partially filled order can still be cancelled — the unfilled remainder is withdrawn and the filled part stands. Read execution.filledQuantity on the order afterwards to see what actually traded.
Errors: 409 already-filled (nothing left to cancel), 409 already-canceled, 409 already-processing, 422 cancel-restricted, 404 order-not-found.
Inputs: order_id (required), account_seq, response_format. Returns: note, orderId, operation, accountSeq
tossinvest_create_conditional_orderCreate a conditional orderADestructive
Register a REAL price-triggered order: watch a symbol and automatically place a buy or sell when the price reaches a trigger. Confirm every parameter with the user first.
Types:
SINGLE — watch one condition ('first'). Either side. LIMIT or MARKET. No per-symbol limit.
OCO (one-cancels-the-other) — watch two conditions at once; when one fires the other is cancelled. Both must be SELL, LIMIT only, and first.trigger_price > current price > second.trigger_price. This is the take-profit / stop-loss bracket on an existing position.
OTO (one-triggers-the-other) — 'second' only starts being watched after 'first' fills. first must be BUY, second must be SELL, LIMIT only. This is buy-then-auto-exit. OCO and OTO are limited to one per symbol; a second one fails with 422 duplicate-conditional-order.
Args:
symbol (string): the symbol to watch.
type ('SINGLE' | 'OCO' | 'OTO').
quantity (string): share count, shared by every leg in the group.
order_type ('LIMIT' | 'MARKET'): shared by every leg. LIMIT requires order_price on each condition; MARKET forbids it. OCO/OTO accept LIMIT only.
expire_date (string): YYYY-MM-DD. The conditional order auto-expires unfired on this date.
first (object): { order_side, trigger_price, order_price? } — the first watched condition.
second (object, optional): same shape. Omit for SINGLE, required for OCO and OTO.
client_order_id (string, optional): idempotency key.
confirm_high_value_order (boolean): default false. Required true at ₩100,000,000 or more.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, conditionalOrderId, clientOrderId, operation: 'created' }.
Errors: 422 condition-already-met when the trigger price has already been reached (pick another price), 422 duplicate-conditional-order, 400 invalid-request for a bad leg combination.
Inputs: type (required), first (required), symbol (required), quantity (required), +7 more. Returns: note, operation, accountSeq, clientOrderId, +1 more
tossinvest_create_orderPlace a stock orderADestructive
Place a REAL buy or sell order for a Korean or US stock. This spends or liquidates actual money — confirm the symbol, side, quantity and price with the user before calling.
Args:
symbol (string): KRX 6 digits or US ticker.
side ('BUY' | 'SELL').
order_type ('LIMIT' | 'MARKET').
quantity (string, optional): number of shares as a decimal string. Whole numbers only, except US market sells, which allow up to 6 decimal places.
order_amount (string, optional): US MARKET orders only — spend this many dollars and let the filled quantity float. Regular US session hours only.
price (string, optional): REQUIRED for LIMIT, forbidden for MARKET. KR: whole won, and it must land on the tick size for the price band. US: up to 4 decimals below $1, 2 decimals at or above $1.
time_in_force ('DAY' | 'CLS'): default DAY. CLS (at-the-close, i.e. LOC when combined with LIMIT) currently works only for US LIMIT orders.
client_order_id (string, optional): idempotency key, max 36 chars of [A-Za-z0-9_-]. Re-sending the same value within 10 minutes returns the original order rather than creating a second one. Strongly recommended.
confirm_high_value_order (boolean): default false. Required true for orders of ₩100,000,000 or more.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Supply exactly one of quantity or order_amount.
Returns { accountSeq, orderId, operation: 'created' }. The response confirms acceptance, NOT execution — call tossinvest_get_order with the returned orderId to see the fill.
Before ordering it is worth checking tossinvest_get_buying_power (buys), tossinvest_get_sellable_quantity (sells) and tossinvest_get_price_limits (limit prices).
Errors: 422 insufficient-buying-power, 422 order-hours-closed, 422 price-out-of-range, 422 opposite-pending-order-exists, 400 confirm-high-value-required, 400 invalid-request with the correct tick size in 'data'.
Inputs: side (required), symbol (required), order_type (required), price, +7 more. Returns: note, orderId, operation, accountSeq
tossinvest_get_buying_powerGet available buying powerARead-onlyIdempotent
Get how much cash is available to buy with, in KRW or USD.
Check this before placing a buy order — an order beyond it fails with 422 insufficient-buying-power.
Args:
currency ('KRW' | 'USD'): KRW for Korean stocks, USD for US stocks.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, currency, cashBuyingPower }. cashBuyingPower is cash-settled buying power only — margin (미수) is excluded, so this is the amount that can be spent without incurring a margin position.
Inputs: currency (required), account_seq, response_format. Returns: currency, accountSeq, cashBuyingPower
tossinvest_get_candlesGet candle chart dataARead-onlyIdempotent
Get OHLCV candles for one stock, newest bar first. Max 200 bars per call.
This is the tool for historical price analysis: trends, ranges, moving averages, "how did X do last month".
Args:
symbol (string): One symbol.
interval ('1m' | '1d'): 1-minute or daily bars.
count (number): 1-200, default 100.
before (string, optional): ISO 8601 upper bound, inclusive — only bars at or before this instant. Pass the previous response's nextBefore to page backwards in time. Omit for the newest bars.
adjusted (boolean): default true. Adjust for splits/dividends. Set false for raw prices.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { symbol, interval, count, candles: [{ timestamp, openPrice, highPrice, lowPrice, closePrice, volume, currency }], nextBefore }. timestamp is the bar's OPEN time. nextBefore is null when no older data exists.
Examples:
"Samsung's last 30 trading days" -> symbol='005930', interval='1d', count=30
"Apple intraday today" -> symbol='AAPL', interval='1m', count=200
For indices use tossinvest_get_market_indicator_candles instead.
Inputs: symbol (required), interval (required), count, before, +2 more. Returns: count, symbol, candles, interval, +3 more
tossinvest_get_commissionsGet trading commission ratesARead-onlyIdempotent
Get the account's trading commission rates for the Korean and US markets.
Use this to estimate trading costs before ordering, or to explain the gap between gross and after-cost profit in holdings.
Args:
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, count, commissions: [{ marketCountry, commissionRate, startDate, endDate }] }. commissionRate is a PERCENT: '0.015' means 0.015% of notional, i.e. multiply notional by 0.00015. startDate/endDate bound a promotional rate; both are null for US, and endDate is null for an open-ended rate.
Inputs: account_seq, response_format. Returns: count, accountSeq, commissions
tossinvest_get_conditional_orderGet conditional order detailARead-onlyIdempotent
Get the full detail of one conditional order by id, active or finished.
Args:
conditional_order_id (string): id from a create/modify response or from tossinvest_list_conditional_orders.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, conditionalOrder: { conditionalOrderId, type, status, symbol, market, quantity, orderType, expireDate, createdAt, first, second } }. Each leg has { type, status, triggerPrice, targetProfitRate, orderPrice, triggeredOrderId }. Leg status values: WATCHING, HOLDING, PAUSED, ORDERING, ORDERED, COMPLETED, EXPIRED, CANCELED.
Errors: 404 conditional-order-not-found — note that modifying a conditional order issues a NEW id and voids the old one, so always use the most recently returned id.
Inputs: conditional_order_id (required), account_seq, response_format. Returns: accountSeq, conditionalOrder
tossinvest_get_exchange_rateGet KRW/USD exchange rateARead-onlyIdempotent
Get the KRW <-> USD exchange rate, refreshed once a minute.
Use this to convert between the KRW and USD figures that holdings and orders report separately.
Args:
base_currency ('KRW' | 'USD'): the currency being priced.
quote_currency ('KRW' | 'USD'): the currency it is priced in. E.g. base='USD', quote='KRW' gives won per dollar.
date_time (string, optional): ISO 8601 instant for a historical rate. Omit for the current rate.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { baseCurrency, quoteCurrency, rate, midRate, basisPoint, rateChangeType, validFrom, validUntil }. rateChangeType is UP, EQUAL or DOWN. validFrom/validUntil bound the ~1-minute window this quote applies to.
This is an indicative display rate — the rate actually applied when an order settles can differ.
Errors: 404 exchange-rate-not-found when no rate exists for the requested instant.
Inputs: base_currency (required), quote_currency (required), date_time, response_format. Returns: rate, midRate, validFrom, basisPoint, +4 more
tossinvest_get_holdingsGet portfolio holdingsARead-onlyIdempotent
Get the account's stock holdings with per-symbol detail and aggregate valuation.
This is the portfolio tool: what is owned, at what average cost, worth how much, up or down how much.
Args:
account_seq (number, optional): which account. Resolved automatically when the credentials have one account.
symbol (string, optional): restrict to one symbol. The summary totals are recomputed for just that symbol.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, count, totalPurchaseAmount, marketValue, profitLoss, dailyProfitLoss, items }.
Summary objects carry per-currency amounts as { krw, usd } — KRW and USD are reported separately, never summed. Convert with tossinvest_get_exchange_rate if a single figure is wanted.
profitLoss has both 'amount'/'rate' (gross) and 'amountAfterCost'/'rateAfterCost' (net of commission and tax). Use the AfterCost variants for realistic returns.
Each item: { symbol, name, marketCountry, currency, quantity, lastPrice, averagePurchasePrice, marketValue: { purchaseAmount, amount, amountAfterCost }, profitLoss, dailyProfitLoss, cost: { commission, tax } }, priced in the symbol's own currency.
Covers KR and US stocks only — overseas derivatives and bonds are excluded. No holdings gives zeroed totals and an empty item list.
Inputs: symbol, account_seq, response_format. Returns: count, items, truncated, accountSeq, +5 more
tossinvest_get_investor_tradingGet investor-type trading flowsARead-onlyIdempotent
Get KRX buy/sell value broken down by investor type for KOSPI or KOSDAQ, newest period first.
This answers "are foreigners buying or selling?" — the classic Korean-market flow question. Net flow = buyAmount - sellAmount.
Args:
symbol ('KOSPI' | 'KOSDAQ'): only these two are supported here.
interval ('1d' | '1w' | '1mo' | '1y'): the period each record aggregates.
count (number): 1-100, default 10.
until (string, optional): YYYY-MM-DD inclusive upper bound. Pass the previous response's nextUntil to page backwards.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { symbol, interval, count, records: [{ date, updatedAt, individual, foreigner, institution, otherCorporation }], nextUntil }. Each investor entry is { buyAmount, sellAmount }; institution additionally carries a 'breakdown' with seven sub-categories (financialInvestment, insurance, trust, privateEquityFund, bank, otherFinancialInstitution, pensionFund) that sum to the institution totals.
All amounts are KRW integers as strings — there is no currency field. 'foreigner' is the total across registered and unregistered foreign investors. Buy totals across the four categories equal sell totals market-wide. The current day's record is provisional until the close; check updatedAt.
Errors: 400 unsupported-symbol for anything other than KOSPI/KOSDAQ.
Inputs: symbol (required), interval (required), count, until, +1 more. Returns: count, symbol, records, interval, +3 more
tossinvest_get_market_calendarGet market trading hoursARead-onlyIdempotent
Get trading-session hours for the Korean or US market across three business days: previous, current and next.
Use this to answer "is the market open?", "when does it open?", or to explain an order-hours-closed rejection. All times are ISO 8601 in KST (+09:00) for BOTH markets — US session times are already converted to Korean time.
Args:
country ('KR' | 'US'): which market.
date (string, optional): YYYY-MM-DD reference date. Omit for today. For US, this is the US local date.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { country, previousBusinessDay, today, nextBusinessDay }, each { date, ...sessions }.
KR: an 'integrated' object (KRX + NXT combined) holding preMarket / regularMarket / afterMarket, each { startTime, endTime }. After-hours single-price and closing-price sessions are excluded.
US: dayMarket, preMarket, regularMarket, afterMarket, each { startTime, endTime } or null. On a holiday all four are null.
Errors: none specific; an invalid date format returns 400 invalid-request.
Inputs: country (required), date, response_format. Returns: today, country, nextBusinessDay, previousBusinessDay
tossinvest_get_market_indicator_candlesGet index or bond yield candlesARead-onlyIdempotent
Get OHLCV history for a Korean index or treasury yield, newest bar first. Max 200 bars per call.
Args:
symbol: one of KOSPI, KOSDAQ, KR_BOND_2Y, KR_BOND_3Y, KR_BOND_5Y, KR_BOND_10Y, KR_BOND_20Y, KR_BOND_30Y.
interval ('1m' | '1d'): '1m' is supported for KOSPI and KOSDAQ ONLY. KR_BOND_* support '1d' only and reject '1m' with 400 invalid-request.
count (number): 1-200, default 100.
before (string, optional): ISO 8601 inclusive upper bound. Pass the previous response's nextBefore to page backwards.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { symbol, interval, count, candles: [{ timestamp, openPrice, highPrice, lowPrice, closePrice, volume }], nextBefore }. For KR_BOND_* the OHLC values are yields in percent, not prices.
Errors: 400 unsupported-symbol outside the catalog; 400 invalid-request for '1m' on a bond symbol.
Inputs: symbol (required), interval (required), count, before, +1 more. Returns: count, symbol, candles, interval, +3 more
tossinvest_get_market_indicator_pricesGet index and bond yield pricesARead-onlyIdempotent
Get the current level of Korean market indices and treasury yields.
Supported symbols (this catalog and nothing else):
KOSPI, KOSDAQ — index level in points
KR_BOND_2Y, KR_BOND_3Y, KR_BOND_5Y, KR_BOND_10Y, KR_BOND_20Y, KR_BOND_30Y — yield in percent ('3.25' means 3.25%)
Args:
symbols (string): Comma-separated catalog symbols, e.g. 'KOSPI,KOSDAQ'.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { count, prices: [{ symbol, lastPrice, timestamp }] }.
For individual stocks use tossinvest_get_prices — this endpoint rejects stock symbols.
Errors: 400 unsupported-symbol for anything outside the catalog.
Inputs: symbols (required), response_format. Returns: count, prices
tossinvest_get_orderGet order detailARead-onlyIdempotent
Get the full detail of one order by id, in any state.
Use this to confirm what happened after placing, modifying or cancelling — especially to read the fill result.
Args:
order_id (string): the orderId returned by a create/modify/cancel call or by tossinvest_list_orders.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, order: { orderId, symbol, side, orderType, timeInForce, status, price, quantity, orderAmount, currency, orderedAt, canceledAt, execution } }. execution = { filledQuantity, averageFilledPrice, filledAmount, commission, tax, filledAt, settlementDate }.
Errors: 404 order-not-found for an unknown id.
Inputs: order_id (required), account_seq, response_format. Returns: order, accountSeq
tossinvest_get_orderbookGet order bookARead-onlyIdempotent
Get the current bid/ask ladder (호가) for one stock.
Use this to judge liquidity and spread before choosing a limit price. For the single last-traded price use tossinvest_get_prices instead — it is cheaper and supports batching.
Args:
symbol (string): One symbol. KRX = 6 digits, US = ticker.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { symbol, currency, timestamp, asks: [{ price, volume }], bids: [{ price, volume }] }. asks are ascending by price (best ask first), bids descending (best bid first). Both arrays may be empty outside trading hours.
Errors: 404 stock-not-found for unknown symbols.
Inputs: symbol (required), response_format. Returns: asks, bids, symbol, currency, +1 more
tossinvest_get_price_limitsGet daily price limitsARead-onlyIdempotent
Get today's upper and lower price limits (상한가/하한가) for one stock.
Check this before placing a limit order: a price outside the band is rejected with 422 price-out-of-range.
Args:
symbol (string): One symbol.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { symbol, currency, timestamp, upperLimitPrice, lowerLimitPrice }. Limits are decimal strings; either can be null for markets without a daily band (US stocks generally have none).
Errors: 404 stock-not-found for unknown symbols.
Inputs: symbol (required), response_format. Returns: symbol, currency, timestamp, lowerLimitPrice, +1 more
tossinvest_get_pricesGet current pricesARead-onlyIdempotent
Get the latest traded price for one or more Korean (KRX) or US stocks.
This is the cheapest way to answer "what is X trading at". Up to 200 symbols in one call, so batch rather than looping.
Args:
symbols (string): Comma-separated symbols, max 200, no spaces. KRX = 6 digits ('005930'), US = ticker ('AAPL').
response_format ('markdown' | 'json'): default 'markdown'.
Returns { count, prices: [{ symbol, lastPrice, currency, timestamp }] }. lastPrice is a decimal string in the symbol's own currency (KRW for KRX, USD for US). timestamp is null when the symbol has not traded yet today.
Examples:
"How much is Samsung Electronics?" -> symbols='005930'
"Compare Apple and Microsoft" -> symbols='AAPL,MSFT'
Don't use for indices (KOSPI/KOSDAQ) or bond yields — use tossinvest_get_market_indicator_prices.
Errors: 404 stock-not-found when a symbol does not exist.
Inputs: symbols (required), response_format. Returns: count, prices, truncated, truncation_message
tossinvest_get_rankingsGet stock rankingsARead-onlyIdempotent
Get a top-100 stock leaderboard by traded value, traded volume, or price change, for the Korean or US market over a chosen period.
This is the discovery tool: "what is moving today", "most actively traded Korean stocks this week", "biggest losers this month".
Args:
type: which leaderboard, and implicitly which metric it is sorted by: MARKET_TRADING_AMOUNT — highest traded value, whole market MARKET_TRADING_VOLUME — highest traded volume, whole market TOP_GAINERS — largest price gain (does NOT support duration='realtime') TOP_LOSERS — largest price drop (does NOT support duration='realtime') TOSS_SECURITIES_TRADING_AMOUNT — highest traded value among Toss Securities fills only TOSS_SECURITIES_TRADING_VOLUME — highest traded volume among Toss Securities fills only
market_country ('KR' | 'US'): which market.
duration ('realtime' | '1d' | '1w' | '1mo' | '3mo' | '6mo' | '1y'): ranking period, in trading days.
exclude_investment_caution (boolean): default false. Filter out symbols under a caution designation.
count (number): 1-100, default 100.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { type, marketCountry, duration, count, rankedAt, rankings: [{ rank, symbol, currency, price: { lastPrice, basePrice, changeRate }, tradingVolume, tradingAmount }] }.
Reading the numbers correctly:
tradingVolume / tradingAmount are cumulative over 'duration'. For TOSS_SECURITIES_* they count Toss Securities fills only; otherwise the whole market.
price.basePrice and price.changeRate are measured from the START of 'duration' for TOP_GAINERS/TOP_LOSERS, but against the PREVIOUS CLOSE for every other type.
Fewer than 'count' items can come back (symbols whose quote lookup failed are dropped).
An uncomputed combination returns an empty list with rankedAt null — not an error.
Symbols come back without names; pass them to tossinvest_get_stocks to resolve company names.
Errors: 400 unsupported-ranking-duration for TOP_GAINERS/TOP_LOSERS with duration='realtime'.
Inputs: type (required), duration (required), market_country (required), count, +2 more. Returns: type, count, duration, rankedAt, +4 more
tossinvest_get_sellable_quantityGet sellable quantityARead-onlyIdempotent
Get how many shares of one symbol can be sold right now.
This can be lower than the holding quantity — shares tied up in an open sell order or not yet settled are excluded. Check it before selling; exceeding it fails with 422 insufficient-sellable-quantity.
Args:
symbol (string): the symbol to check.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, symbol, sellableQuantity }. KR quantities are whole shares; US quantities can be fractional.
Inputs: symbol (required), account_seq, response_format. Returns: symbol, accountSeq, sellableQuantity
tossinvest_get_stocksGet stock reference dataARead-onlyIdempotent
Get reference/master data for one or more symbols: names, listing market, security type, currency, listing status and shares outstanding.
Use this to resolve what a symbol actually is, to check a symbol is still listed and tradable before ordering, or to get the shares-outstanding figure needed for a market-cap calculation (market cap = lastPrice x sharesOutstanding).
Args:
symbols (string): Comma-separated symbols, max 200, no spaces.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { count, stocks: [{ symbol, name, englishName, isinCode, market, securityType, isCommonShare, status, currency, listDate, delistDate, sharesOutstanding, leverageFactor, koreanMarketDetail }] }.
market: KOSPI, KOSDAQ, NYSE, NASDAQ, AMEX, KR_ETC, US_ETC
securityType: STOCK, FOREIGN_STOCK, DEPOSITARY_RECEIPT, INFRASTRUCTURE_FUND, REIT, ETF, FOREIGN_ETF, ETN, STOCK_WARRANTS
status: SCHEDULED (not yet listed), ACTIVE, DELISTED
isCommonShare: false for preferred shares
koreanMarketDetail (KR symbols only): { liquidationTrading, nxtSupported, krxTradingSuspended, nxtTradingSuspended }
This does NOT search by company name — it takes symbols only. It also returns no prices; use tossinvest_get_prices for those.
Errors: 404 stock-not-found when a symbol does not exist.
Inputs: symbols (required), response_format. Returns: count, stocks, truncated, truncation_message
tossinvest_get_stock_warningsGet stock purchase warningsARead-onlyIdempotent
Get the currently active trading warnings and volatility-interruption (VI) flags for one symbol.
Check this before buying anything unfamiliar — these flags mark designations that restrict or endanger trading.
Args:
symbol (string): One symbol.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { symbol, count, warnings: [{ warningType, exchange, startDate, endDate }] }, sorted by startDate descending. warningType values:
LIQUIDATION_TRADING (정리매매) — delisting liquidation period
OVERHEATED (단기과열)
INVESTMENT_WARNING (투자경고) / INVESTMENT_RISK (투자위험)
VI_STATIC / VI_DYNAMIC / VI_STATIC_AND_DYNAMIC — volatility interruption triggered
STOCK_WARRANTS (신주인수권) endDate is null while a designation is still open-ended.
An existing symbol with no active warnings returns count 0 and an empty list — that is a clean result, not an error. VI flags update within seconds; exchange designations update on a daily batch.
Errors: 404 stock-not-found when the symbol does not exist.
Inputs: symbol (required), response_format. Returns: count, symbol, warnings
tossinvest_get_tradesGet recent tradesARead-onlyIdempotent
Get today's most recent executed trades (체결 내역) for one stock, newest first.
Useful for gauging very recent momentum and actual traded sizes. Only covers the current session — it is not a historical trade archive.
Args:
symbol (string): One symbol.
count (number): 1-50, default 50.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { symbol, count, trades: [{ price, volume, timestamp, currency }] }. Returns an empty list before the session's first trade.
Errors: 404 stock-not-found for unknown symbols.
Inputs: symbol (required), count, response_format. Returns: count, symbol, trades, truncated, +1 more
tossinvest_list_accountsList brokerage accountsARead-onlyIdempotent
List the Toss Securities accounts reachable with the configured credentials.
Call this first when you do not know which account to act on. The 'accountSeq' in the response is what every account-scoped tool takes as 'account_seq'.
Args:
response_format ('markdown' | 'json'): default 'markdown'.
Returns { count, accounts: [{ accountNo, accountSeq, accountType }] }. Only BROKERAGE (종합매매) accounts are exposed today; child accounts are not usable. An empty list means the credentials have no brokerage account.
When exactly one account exists, other tools resolve it automatically, so you rarely need to pass account_seq by hand.
Rate limit: the ACCOUNT group allows only 1 request per second.
Inputs: response_format. Returns: count, accounts
tossinvest_list_conditional_ordersList conditional ordersARead-onlyIdempotent
List the account's conditional (price-triggered) orders.
This returns conditional orders from every channel, including ones set up in the Toss Securities app — not just those created through this API.
Args:
status ('OPEN' | 'CLOSED'): OPEN covers WATCHING, PAUSED, ORDERING and ORDERED. CLOSED covers COMPLETED and EXPIRED.
symbol (string, optional): restrict to one symbol.
cursor (string, optional): pagination cursor from a previous nextCursor.
limit (number): 1-100, default 20.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, status, count, conditionalOrders: [{ conditionalOrderId, type, status, symbol, market, quantity, orderType, expireDate, createdAt, first, second }], nextCursor, hasNext }. type is SINGLE, OCO or OTO; there is no server-side type filter, so filter on this field yourself. Each condition leg carries { type, status, triggerPrice, targetProfitRate, orderPrice, triggeredOrderId }; triggeredOrderId links to the real order created on trigger, which you can then read with tossinvest_get_order.
Inputs: status (required), limit, cursor, symbol, +2 more. Returns: count, status, hasNext, truncated, +4 more
tossinvest_list_ordersList ordersARead-onlyIdempotent
List the account's orders, filtered by lifecycle group.
Args:
status ('OPEN' | 'CLOSED'): OPEN returns still-working orders (individual status PENDING, PARTIAL_FILLED, PENDING_CANCEL, PENDING_REPLACE). CLOSED returns finished ones (FILLED, CANCELED, REJECTED, REPLACED, CANCEL_REJECTED, REPLACE_REJECTED, PARTIAL_FILLED).
symbol (string, optional): restrict to one symbol.
from / to (string, optional): YYYY-MM-DD inclusive bounds on order creation time (orderedAt, KST). Omit for all time.
cursor (string, optional): pagination cursor from a previous nextCursor. CLOSED only.
limit (number): 1-100, default 20. CLOSED only.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Paging differs by status: OPEN returns every working order in one shot and ignores cursor/limit (nextCursor is always null, hasNext always false); CLOSED honours cursor and limit.
Returns { accountSeq, status, count, orders: [...], nextCursor, hasNext }. Each order carries an 'execution' object: { filledQuantity, averageFilledPrice, filledAmount, commission, tax, filledAt, settlementDate }. filledQuantity is 0 when nothing has filled — check it on CANCELED and REJECTED orders too, since those can be partially filled.
Note the two status vocabularies: the 'status' argument is a GROUP label, while 'orders[].status' is the individual order state.
Inputs: status (required), to, from, limit, +4 more. Returns: count, orders, status, hasNext, +4 more
tossinvest_modify_conditional_orderModify a conditional orderADestructive
Replace an existing conditional order's settings. This changes a REAL standing order — confirm with the user first.
IMPORTANT: modification works by cancelling and recreating, so a NEW conditionalOrderId is issued and the old one stops working. Use the id from this response for every later read, modify or cancel.
The whole conditional order is re-specified, so pass every leg you want to keep — anything omitted is dropped. The symbol cannot change (it is fixed by the id), and switching type (e.g. SINGLE to OCO) is allowed.
Args:
conditional_order_id (string): the conditional order to replace.
type ('SINGLE' | 'OCO' | 'OTO'): the resulting type.
quantity (string): share count, shared by every leg.
order_type ('LIMIT' | 'MARKET'): shared by every leg. OCO/OTO accept LIMIT only.
expire_date (string): YYYY-MM-DD. Required here even though it is optional in some clients.
first (object): { order_side, trigger_price, order_price? }.
second (object, optional): omit for SINGLE, required for OCO and OTO.
confirm_high_value_order (boolean): default false.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, conditionalOrderId, operation: 'modified' } — with the NEW id.
Errors: 404 conditional-order-not-found, 422 condition-already-met.
Inputs: type (required), first (required), quantity (required), order_type (required), +6 more. Returns: note, operation, accountSeq, clientOrderId, +1 more
tossinvest_modify_orderModify an open orderADestructive
Change the price (and, for Korean stocks, the quantity) of a working order. This alters a REAL order — confirm the new terms with the user first.
Args:
order_id (string): the order to modify. Must still be working; get it from tossinvest_list_orders with status='OPEN'.
order_type ('LIMIT' | 'MARKET'): the resulting order type.
quantity (string, optional): REQUIRED for Korean stocks, whole numbers only. MUST BE OMITTED for US stocks, which reject it with 400 us-modify-quantity-not-supported. US modifications can only change price.
price (string, optional): REQUIRED for LIMIT, forbidden for MARKET. Same tick/decimal rules as placing an order.
confirm_high_value_order (boolean): default false. Required true at ₩100,000,000 or more. Orders of ₩3,000,000,000 or more are rejected regardless.
account_seq (number, optional): resolved automatically for single-account credentials.
response_format ('markdown' | 'json'): default 'markdown'.
Returns { accountSeq, orderId, operation: 'modified' }.
Errors: 409 already-filled / already-canceled / already-modified / already-processing, 422 modify-restricted, 404 order-not-found.
Inputs: order_id (required), order_type (required), price, quantity, +3 more. Returns: note, orderId, operation, accountSeq
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Every tool has a clearly distinct purpose: get_prices vs get_orderbook vs get_trades vs get_candles all target different data facets, and order management tools are cleanly separated from conditional order tools. No two tools overlap in function, so an agent can confidently select the right one.
All tools follow a consistent verb_noun pattern with snake_case, prefixed by tossinvest_. Get_/list_ for retrieval, create_/modify_/cancel_ for mutations, and the noun clearly indicates the resource (orders, holdings, prices, etc.). This is a model of consistent naming.
At 28 tools, the count exceeds the typical well-scoped range (3-15) and pushes into the heavy category. However, the domain is a comprehensive trading platform covering two markets, market data, orders, conditional orders, and account management, so each tool serves a distinct need. It's on the upper edge but not unreasonable.
The tool surface is remarkably complete: full CRUD for orders and conditional orders, comprehensive market data (prices, candles, orderbook, trades, limits, indicators, rankings, investor flow), account management (holdings, buying power, sellable quantity, commissions), plus reference data, warnings, exchange rates, and calendar. No significant dead ends or missing lifecycle operations.
Maintenance
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
China A-share market data over MCP: 22 tools for quotes, K-line, financials, money flow, top-trader boards, sectors, macro, convertible bonds and factor screening. Five tools need no API key, so you can connect and try it immediately.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server wrapping Toss Securities Open API, enabling stock price queries and trading for Korean and US stocks via natural language.36265 npmMIT
- AlicenseCqualityCmaintenanceSafe-by-default MCP server for the official Toss Securities Open API, providing read-only market and account data with optional order operations protected by multiple safety gates.272MIT
- AlicenseBqualityBmaintenanceToss Securities (토스증권) Open API MCP server for the Korean stock market. Supports real-time quotes, orderbook, candles, account holdings, buying power, and order management (create/modify/cancel) with a built-in safety gate requiring explicit confirmation before any real order is placed.36297 npm4MIT
- AlicenseAqualityDmaintenanceA local MCP server that automatically generates tools from Toss Securities' official OpenAPI spec, enabling real API calls with multi-layered order safety and OAuth 2.0 authentication.361MIT