MCP server¶
kiwoom-client-mcp exposes the Kiwoom REST API as MCP (Model Context Protocol) tools. Agents such as Claude Code, Claude Desktop, Cursor and Codex can look up quotes, charts, rankings and your account directly. On a live account the order tools are not even registered until you turn them on yourself.
Install¶
The quickest way is to run it with uv, with nothing installed:
You can also install it with pip. You need the [mcp] extra (mcp>=2.0):
Get an app key and secret from the Kiwoom REST API portal. Start with a paper-trading (모의투자) key. Paper and live keys are different, and using one against the other server fails with error 8030.
Add it to your client¶
The config command prints a ready-to-paste snippet for each client. Keys come out as YOUR_APP_KEY placeholders and the default is paper trading. The command needs no keys and no network.
kiwoom-client-mcp config claude-code # a `claude mcp add` command
kiwoom-client-mcp config claude-desktop # JSON to merge into claude_desktop_config.json
kiwoom-client-mcp config cursor # ~/.cursor/mcp.json or .cursor/mcp.json
kiwoom-client-mcp config codex # ~/.codex/config.toml
The snippet goes to stdout and the "where to put it" note goes to stderr, so > mcp.json saves valid JSON. The options are:
| Option | Effect |
|---|---|
--live |
KIWOOM_IS_MOCK=false (lookups on the live server). Order tools stay off |
--toolsets market,chart |
expose only these modules |
--discovery |
expose only three meta tools (see "Saving context" below) |
--launcher installed |
use kiwoom-client-mcp from PATH instead of uvx |
Environment variables and options¶
| Env var | CLI | Meaning | Default |
|---|---|---|---|
KIWOOM_APP_KEY, KIWOOM_APP_SECRET |
— | App key and secret (required to serve) | — |
KIWOOM_IS_MOCK |
--mock |
paper-trading server. Accepts true/false, 1/0, yes/no; anything else is an error | false (live) |
KIWOOM_MCP_TOOLSETS |
--toolsets |
modules to expose, comma-separated. all = every module |
all |
KIWOOM_MCP_MODE |
--discovery |
discovery = three meta tools only |
everything listed |
KIWOOM_MCP_MAX_ROWS |
--max-rows |
default row limit for list responses | no limit |
KIWOOM_MCP_ALLOW_LIVE_ORDERS |
(none) | expose order tools on a live account | false |
CLI options win over environment variables. The live-order opt-in deliberately has no CLI option.
Toolset names are the endpoint module names: account, stock_info, market, chart, order, credit_order, ranking, sector, foreign_institution, short_selling, slb, theme, condition_search, elw, etf.
Live-order guard¶
- When
KIWOOM_IS_MOCK=false(live) andKIWOOM_MCP_ALLOW_LIVE_ORDERSis nottrue, the server does not register the order tools (8order_*, 4credit_order_*). They do not appear in the tool list,call_tool,search_toolsorkiwoom://tools. - The toolset filter, discovery mode and the helper tools only ever see what the guard left. Picking
--toolsets orderdoes not bring order tools back without the opt-in. A regression test (tests/test_mcp_live_order_regression.py) pins this. - Paper trading (
KIWOOM_IS_MOCK=true) has no real fills, so the order tools are always available there. - The guard exists only on the MCP server path. Using
KiwoomAPI/AsyncKiwoomAPIfrom Python is not gated.
Order tools carry the destructiveHint=true annotation so clients can ask before running them. Lookup tools carry readOnlyHint=true.
Order preview: order_preview¶
order_preview sends nothing (no network call). It returns:
- the price snapped to the tick size (down for a buy, up for a sell)
- field checks
- the estimated amount
- warnings
- the exact
paramsto hand to the order tool
order_tools_enabled says whether this server has order tools at all. An agent should show the preview to the user and place an order only after explicit confirmation. The server's instructions and the order_checklist prompt describe that sequence.
Tools¶
| Kind | Name | Notes |
|---|---|---|
| Helpers | stock_search |
find a stock by name or code (ka10099, cached) |
stock_snapshot |
price, change, market cap, PER/PBR and more in one call (ka10001) | |
account_summary |
account totals, P&L and holdings (kt00018) | |
order_preview |
order preview, never sent | |
| TR tools | <module>_<method> |
e.g. stock_info_basic_stock_info, chart_stock_daily_chart. Full list |
| Condition search | 4 condition_search_* tools |
WebSocket. Real-time registration returns the first reply only |
TR tools take Kiwoom request fields, as strings, under params. Each tool's input schema lists the field names, whether they are required and what they mean, from the TR catalog.
To fetch the next page, pass the response's cont-yn/next-key back as cont_yn="Y" and next_key.
Saving context¶
Every tool definition lands in the agent's context. The size of tools/list by setting:
| Setting | Tools | tools/list size (characters) |
|---|---|---|
| everything (live, guarded) | 178 | about 220 K |
--toolsets market,chart,account |
80 | about 97 K |
--discovery |
3 | about 1.5 K |
(Each TR tool's input schema lists its request field IDs and Korean names, which makes them large.)
- Toolsets: turn on only the modules you use.
- Discovery mode: use every TR through three tools:
search_tools(keyword or toolset search) →describe_tool(input schema) →call_tool(run). max_rows: passmax_rowsto any lookup tool to keep only the first N rows of each list in the response. Set a server-wide default with--max-rows. A cut response carries"_truncated": {"<key>": {"total": 300, "returned": 20}}.
Resources and prompts¶
| URI | Content |
|---|---|
kiwoom://guide |
usage rules for agents |
kiwoom://tools |
the tools exposed right now (name, toolset, read-only, api_id) |
kiwoom://codes/trade-types |
order type trde_tp and exchange dmst_stex_tp codes |
kiwoom://codes/markets |
market codes mrkt_tp (ka10099) |
kiwoom://tr/{api_id} |
request and response fields of one TR (e.g. kiwoom://tr/ka10001) |
There are three prompts:
analyze_stock(stock): analyse one stock, lookups onlyreview_account(): check your account, lookups onlyorder_checklist(request): build a preview and never order before the user confirms
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
KIWOOM_APP_KEY and KIWOOM_APP_SECRET ... must be set |
put the keys in the client config's env |
MCP 서버에는 mcp 패키지가 필요합니다 |
installed without the [mcp] extra. Use pip install 'kiwoom-client[mcp]' or uvx --from 'kiwoom-client[mcp]' ... |
ImportError: ServerRequestContext |
an old mcp 1.x is installed. Run pip install -U 'mcp>=2.0,<3' |
KIWOOM_IS_MOCK=... 를 해석할 수 없습니다 |
use true/false (or 1/0, yes/no) |
| error 8030/8031 | the paper/live key does not match KIWOOM_IS_MOCK |
| no order tools | intended (live server without the opt-in). Test on paper trading, or see "Live-order guard" above |