KIS MCP Server
ํ๊ตญํฌ์์ฆ๊ถ mcp server
Ask AI about KIS MCP Server
Powered by Claude ยท Grounded in docs
I know everything about KIS MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ํ๊ตญํฌ์์ฆ๊ถ REST API MCP (Model Context Protocol)
ํ๊ตญํฌ์์ฆ๊ถ(KIS) REST API๋ฅผ MCP ๋๊ตฌ๋ก ํธ์ถํ๋ ์๋ฒ์ ๋๋ค. ๊ตญ๋ด/ํด์ธ ์ฃผ์ ์กฐํ, ๊ณ์ข ์กฐํ, ์ฃผ๋ฌธ ๊ด๋ จ API๋ฅผ ์นดํ๋ก๊ทธ ๊ธฐ๋ฐ ๋ฒ์ฉ ๋๊ตฌ์ ์์ฃผ ์ฐ๋ ํธ์ ๋๊ตฌ๋ก ์ ๊ณตํฉ๋๋ค.
์ฃผ์ ๊ธฐ๋ฅ
- API ์นดํ๋ก๊ทธ ๊ธฐ๋ฐ ํธ์ถ
- 8๊ฐ ๊ทธ๋ฃน, 166๊ฐ REST API ์ ๊ณต
- API ๊ทธ๋ฃน/ID, ๊ฒฝ๋ก, HTTP ๋ฉ์๋, TR_ID ํ๋ณด, ์์ฒญ ํ๋ผ๋ฏธํฐ ํ์ธ
- ํ๋ผ๋ฏธํฐ๋ณ ํ๊ธ ๋ผ๋ฒจ, ์ ๋ ฅ ๊ฐ์ด๋, ์์๊ฐ, ์ฃผ์ ์ฝ๋๊ฐ ์ ๊ณต
- ์ ์ฒด ๋ชฉ๋ก:
API_CATALOG.md
- ๊ตญ๋ด์ฃผ์
- ํ์ฌ๊ฐ, ๊ธฐ๊ฐ/์ผ๋ณ ์์ธ, ํธ๊ฐ, ์ ์ข ์ง์, ๊ธฐ๋ณธ์ ๋ณด ์กฐํ
- ์๊ณ , ํฌ์๊ณ์ข ์์ฐํํฉ, ๋งค์๊ฐ๋ฅ๊ธ์ก, ๋งค๋๊ฐ๋ฅ์๋ ์กฐํ
- ์ฃผ๋ฌธ/์ฃผ๋ฌธ๋ด์ญ/์ ์ ์ทจ์ ๊ฐ๋ฅ ์ฃผ๋ฌธ ์กฐํ
- ํด์ธ์ฃผ์
- ๋ฏธ๊ตญ, ์ผ๋ณธ, ์ค๊ตญ, ํ์ฝฉ, ๋ฒ ํธ๋จ ์์ฅ ์ฝ๋ ์ง์
- ํ์ฌ๊ฐ, ์๊ณ , ์ฒด๊ฒฐ๊ธฐ์ค ํ์ฌ์๊ณ , ํตํ๋ณ ์ฆ๊ฑฐ๊ธ, ๋งค์๊ฐ๋ฅ๊ธ์ก ์กฐํ
- ์์ฅ/๋งค์๋งค๋ ๋ฐฉํฅ์ ๋ฐ๋ฅธ ์ฃผ๋ฌธ TR_ID ์๋ ์ ํ
- ์คํ/์ด์
stdio,sse,streamable-httptransport ์ง์.env๋๋ ๋ช ๋ น์ค ์ธ์ ๊ธฐ๋ฐ ์ค์ - ๊ณ์ข๋ฒํธ, ๊ณ์ข์ํ์ฝ๋, ์ธ์ฆ๊ฐ ์๋ ๋ณด์
- ์ฑํค์ ๊ณ์ข ํ์ ๊ธฐ์ค ํ ํฐ ์บ์
- ์ ์ ์๋ ์์ฒญ ํ๋ผ๋ฏธํฐ ๊ธฐ๋ณธ ๊ฑฐ๋ถ
- ์ฃผ๋ฌธ/์ ์ /์ทจ์ API ๊ธฐ๋ณธ ์ฐจ๋จ
์์ ๊ธฐ๋ณธ๊ฐ
์ฃผ๋ฌธ/์ ์ /์ทจ์์ฒ๋ผ ๊ณ์ข ์ํ๋ฅผ ๋ฐ๊พธ๋ API๋ ๊ธฐ๋ณธ์ ์ผ๋ก ์ฐจ๋จ๋ฉ๋๋ค.
KIS_ENABLE_TRADING=true
์ ๊ฐ์ ๋ช ์์ ์ผ๋ก ์ค์ ํ ๊ฒฝ์ฐ์๋ง ์ํ ๋ณ๊ฒฝ API๊ฐ ์คํ๋ฉ๋๋ค. ์กฐํ API๋ง ์ฌ์ฉํ๋ ๊ฒฝ์ฐ์๋ ์ค์ ํ์ง ๋ง์ธ์.
์๊ตฌ ์ฌํญ
- Python >= 3.13
- uv
์ค์น
์ค์น๋ INSTALL.md๋ฅผ ๊ธฐ์ค์ผ๋ก ์งํํ์ธ์. LLM์ด๋ MCP ํด๋ผ์ด์ธํธ๊ฐ ์ค์ ํ ๋๋ ์ด ํ์ผ์ ์ฐ์ ์ฝ์ผ๋ฉด ๋ฉ๋๋ค.
INSTALL.md์๋ ๋ค์ ๋ด์ฉ์ด ํฌํจ๋์ด ์์ต๋๋ค.
uv๊ธฐ๋ฐ ์์กด์ฑ ์ค์น.env์์ฑ๊ณผKIS_APP_KEY,KIS_APP_SECRET,KIS_CANO,KIS_ACNT_PRDT_CD์ค์ - Codex CLI, Claude Code, Claude Desktop, ์ผ๋ฐ MCP ํด๋ผ์ด์ธํธ ๋ฑ๋ก ์์
- ์ปจํ
์คํธ ์ ์ฝ์ฉ
KIS_MCP_TOOLSET=catalog์ค์ - ์๊ณ , ๋งค์๊ฐ๋ฅ๊ธ์ก, ํ์ฌ๊ฐ ์กฐํ์ฉ
call-kis-api์์
๋น ๋ฅธ ๋ก์ปฌ ์ค๋น:
pip install uv
uv sync
cp .env.example .env
chmod 600 .env
๊ทธ ๋ค์ .env์ ์๋ ๊ฐ์ ์ค์ ํฉ๋๋ค. ์์ธํ ๊ฐ ์ค๋ช
๊ณผ ํด๋ผ์ด์ธํธ๋ณ ๋ฑ๋ก ๋ช
๋ น์ INSTALL.md๋ฅผ ์ฐธ๊ณ ํ์ธ์.
KIS_APP_KEY="๋ฐ๊ธ๋ฐ์ ์ฑํค"
KIS_APP_SECRET="๋ฐ๊ธ๋ฐ์ ์ํฌ๋ฆฟํค"
KIS_ACCOUNT_TYPE="REAL" # REAL ๋๋ VIRTUAL
KIS_CANO="๊ณ์ข๋ฒํธ ์ 8์๋ฆฌ"
KIS_ACNT_PRDT_CD="01"
KIS_MCP_TOOLSET="catalog"
์คํ
# stdio, ๋ก์ปฌ MCP ํด๋ผ์ด์ธํธ ๊ถ์ฅ
uv run python server.py
๋ช ๋ น์ค ์ธ์๋ก๋ ์ค์ ํ ์ ์์ต๋๋ค.
uv run python server.py \
--app-key "์ฑํค" \
--app-secret "์ํฌ๋ฆฟํค" \
--account-type "REAL" \
--cano "๊ณ์ข๋ฒํธ" \
--acnt-prdt-cd "01"
Transport ์ ํ:
MCP_TYPE=stdio uv run python server.py
MCP_TYPE=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run python server.py
MCP_TYPE=sse MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/sse uv run python server.py
MCP ํด๋ผ์ด์ธํธ ๋ฑ๋ก ์์:
์๋๋ ์ผ๋ฐ MCP ํด๋ผ์ด์ธํธ์ฉ ์ต์ ์์์
๋๋ค. Codex CLI, Claude Code, Claude Desktop ๋ช
๋ น์ INSTALL.md๋ฅผ ์ฌ์ฉํ์ธ์.
{
"mcpServers": {
"kis-mcp-server": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "<project-root>",
"env": {
"KIS_MCP_TOOLSET": "catalog",
"KIS_MCP_LOG_LEVEL": "WARNING"
}
}
}
}
MCP ๋๊ตฌ ๊ตฌ์ฑ
์นดํ๋ก๊ทธ ๋๊ตฌ
| ๋๊ตฌ | ์ค๋ช |
|---|---|
list-kis-api-specs | API ๊ทธ๋ฃน/๊ฒ์์ด ๊ธฐ์ค ๋ชฉ๋ก ์กฐํ |
get-kis-api-spec | ๋จ์ผ API์ ๊ฒฝ๋ก, TR_ID ํ๋ณด, ํ๋ผ๋ฏธํฐ ํ์ธ |
call-kis-api | group, api_type, params๋ก ์นดํ๋ก๊ทธ API ํธ์ถ |
list-kis-api-specs๋ ํ์ ํ๋ผ๋ฏธํฐ์ ๋ผ๋ฒจ, ์์๊ฐ, ์ฃผ์ ์ฝ๋๊ฐ์ ํจ๊ป ๋ฐํํฉ๋๋ค.
get-kis-api-spec๋ ์ ์ฒด ํ๋ผ๋ฏธํฐ์ label, guide, examples, values, default, auto_fill ์ ๋ณด๋ฅผ ๋ฐํํ๋ฏ๋ก LLM์ด ํธ์ถ์ ํ์ํ ์
๋ ฅ ํํ๋ฅผ ๋ฐ๋ก ํ์ธํ ์ ์์ต๋๋ค.
call-kis-api๋ ๋ค์ ์ฒ๋ฆฌ๋ฅผ ๊ณตํต์ผ๋ก ์ํํฉ๋๋ค.
- ํ๊ฒฝ๋ณ์ ๊ธฐ๋ฐ ๊ณ์ข๋ฒํธ/๊ณ์ข์ํ์ฝ๋ ์๋ ์ ๋ ฅ
- ์ธ์ฆ ํ ํฐ ๋ฐ๊ธ ๋ฐ ์บ์
- GET/POST ์์ฒญ ๊ตฌ์ฑ
- ๋ค์ค TR_ID ์ค ์๋ ํ๋ณ ๊ฐ๋ฅํ ์ฃผ๋ฌธ TR_ID ์ ํ
- ์ํ ๋ณ๊ฒฝ API ์์ ๊ฒ์ดํธ ์ ์ฉ
- ์นดํ๋ก๊ทธ์ ์๋ ํ๋ผ๋ฏธํฐ ๊ธฐ๋ณธ ๊ฑฐ๋ถ
ํธ์ ๋๊ตฌ
์์ฃผ ์ฐ๋ ๊ตญ๋ด/ํด์ธ ์ฃผ์ ๊ธฐ๋ฅ์ ๋ณ๋ MCP ๋๊ตฌ๋ก๋ ์ ๊ณตํฉ๋๋ค.
| ๋๊ตฌ | ์ค๋ช |
|---|---|
inquery-stock-price | ๊ตญ๋ด์ฃผ์ ํ์ฌ๊ฐ ์กฐํ |
inquery-balance | ๊ตญ๋ด์ฃผ์ ์๊ณ ์กฐํ |
inquery-order-list | ๊ตญ๋ด์ฃผ์ ์ผ๋ณ ์ฃผ๋ฌธ/์ฒด๊ฒฐ ์กฐํ |
inquery-order-detail | ๊ตญ๋ด์ฃผ์ ์ฃผ๋ฌธ ์์ธ ์กฐํ |
inquery-stock-info | ๊ตญ๋ด์ฃผ์ ์ผ๋ณ ์์ธ ์กฐํ |
inquery-stock-history | ๊ตญ๋ด์ฃผ์ ๊ธฐ๊ฐ ์์ธ ์กฐํ |
inquery-stock-ask | ๊ตญ๋ด์ฃผ์ ํธ๊ฐ ์กฐํ |
inquery-stock-market | ๊ตญ๋ด ์ ์ข /์ง์ ํ์ฌ๊ฐ ์กฐํ |
inquery-stock-basic-info | ๊ตญ๋ด์ฃผ์ ๊ธฐ๋ณธ์ ๋ณด ์กฐํ |
inquery-overseas-stock-price | ํด์ธ์ฃผ์ ํ์ฌ๊ฐ ์กฐํ |
order-stock | ๊ตญ๋ด์ฃผ์ ๋งค์/๋งค๋ ์ฃผ๋ฌธ |
order-overseas-stock | ํด์ธ์ฃผ์ ๋งค์/๋งค๋ ์ฃผ๋ฌธ |
์ฃผ๋ฌธ ๋๊ตฌ๋ KIS_ENABLE_TRADING=true๊ฐ ์์ผ๋ฉด ์คํ๋์ง ์์ต๋๋ค.
๋๊ตฌ ๋ก๋ ์ต์ ํ
MCP ํด๋ผ์ด์ธํธ๋ ์๋ฒ ์ฐ๊ฒฐ ์ ๋๊ตฌ ์ด๋ฆ, ์ค๋ช , ์ ๋ ฅ ์คํค๋ง๋ฅผ ์ปจํ ์คํธ์ ์ฌ๋ฆฝ๋๋ค. ํธ์ ๋๊ตฌ๋ฅผ ๋ง์ด ๋ ธ์ถํ ์๋ก ๋ํ ์์ ์์ ์ ์ปจํ ์คํธ ์ฌ์ฉ๋์ด ๋์ด๋๋ฏ๋ก, ํ์ํ ๊ฒฝ์ฐ ์นดํ๋ก๊ทธ ๋๊ตฌ 3๊ฐ๋ง ๋ ธ์ถํ๋ ๊ฒฝ๋ ๋ชจ๋๋ฅผ ์ฌ์ฉํ ์ ์์ต๋๋ค.
KIS_MCP_TOOLSET=catalog uv run python server.py
| ๊ฐ | ๋ ธ์ถ ๋๊ตฌ ์ | ๋ ธ์ถ ๋๊ตฌ | ์ฉ๋ |
|---|---|---|---|
full | 15๊ฐ | ์นดํ๋ก๊ทธ ๋๊ตฌ + ํธ์ ๋๊ตฌ ์ ์ฒด | ๊ธฐ์กด ๋์๊ณผ ํธํ |
catalog | 3๊ฐ | list-kis-api-specs, get-kis-api-spec, call-kis-api | ๋ฎ์ ์ปจํ ์คํธ ์ฌ์ฉ๋ |
catalog ๋ชจ๋๋ MCP ๋๊ตฌ ์คํค๋ง ๋ก๋๋์ ์ค์ด๊ธฐ ์ํ ๋ชจ๋์
๋๋ค. ํธ์ ๋๊ตฌ๋ ์จ๊ธฐ์ง๋ง, 166๊ฐ API๋ ๊ทธ๋๋ก call-kis-api๋ก ํธ์ถํ ์ ์์ต๋๋ค. ํ์ํ API๋ list-kis-api-specs๋ก ์ฐพ๊ณ , ํ์ํ ์์ธ ํ๋ผ๋ฏธํฐ๋ get-kis-api-spec๋ก ๊ทธ๋๊ทธ๋ ์กฐํํ๋ฉด ๋ฉ๋๋ค.
๊ถ์ฅ ์ฌ์ฉ ํ๋ฆ:
list-kis-api-specs๋ก API๋ฅผ ๊ฒ์ํฉ๋๋ค.get-kis-api-spec๋ก ํ์ ํ๋ผ๋ฏธํฐ, ์์๊ฐ, ์ฝ๋๊ฐ์ ํ์ธํฉ๋๋ค.call-kis-api๋ก ์ค์ API๋ฅผ ํธ์ถํฉ๋๋ค.
MCP ํด๋ผ์ด์ธํธ ์ค์ ์์๋ ํ๊ฒฝ๋ณ์๋ง ์ถ๊ฐํ๋ฉด ๋ฉ๋๋ค.
{
"env": {
"KIS_MCP_TOOLSET": "catalog"
}
}
์์ฃผ ์ฐ๋ ํธ์ ๋๊ตฌ๋ฅผ ๋๊ตฌ ๋ชฉ๋ก์ ์ง์ ๋
ธ์ถํ๊ณ ์ถ์ผ๋ฉด ๊ธฐ๋ณธ๊ฐ์ธ full์ ์ฌ์ฉํ์ธ์.
call-kis-api ์์
๊ตญ๋ด์ฃผ์ ํ์ฌ๊ฐ:
{
"group": "domestic_stock",
"api_type": "inquire_price",
"params": {
"fid_cond_mrkt_div_code": "J",
"fid_input_iscd": "005930"
}
}
ํด์ธ์ฃผ์ ์๊ณ :
{
"group": "overseas_stock",
"api_type": "inquire_balance",
"params": {
"ovrs_excg_cd": "NASD",
"tr_crcy_cd": "USD"
}
}
ํด์ธ์ฃผ์ ์ฒด๊ฒฐ๊ธฐ์ค ํ์ฌ์๊ณ :
{
"group": "overseas_stock",
"api_type": "inquire_present_balance",
"params": {
"wcrc_frcr_dvsn_cd": "01",
"natn_cd": "000",
"tr_mket_cd": "00",
"inqr_dvsn_cd": "00"
}
}
ํด์ธ์ฃผ์ ๋งค์๊ฐ๋ฅ๊ธ์ก:
{
"group": "overseas_stock",
"api_type": "inquire_psamount",
"params": {
"ovrs_excg_cd": "NASD",
"ovrs_ord_unpr": "1",
"item_cd": "QQQ"
}
}
์ฃผ์ API ๊ทธ๋ฃน
| ๊ทธ๋ฃน | ์ค๋ช | API ์ |
|---|---|---|
auth | ์ธ์ฆ | 2 |
domestic_stock | ๊ตญ๋ด์ฃผ์ | 74 |
overseas_stock | ํด์ธ์ฃผ์ | 34 |
domestic_bond | ๊ตญ๋ด์ฑ๊ถ | 14 |
domestic_futureoption | ๊ตญ๋ด์ ๋ฌผ์ต์ | 20 |
overseas_futureoption | ํด์ธ์ ๋ฌผ์ต์ | 19 |
elw | ELW | 1 |
etfetn | ETF/ETN | 2 |
์ ์ฒด API ID, ๊ฒฝ๋ก, TR_ID, ํ์ ํ๋ผ๋ฏธํฐ ๊ฐ์ด๋๋ API_CATALOG.md์ ์ ๋ฆฌ๋์ด ์์ต๋๋ค.
ํ๊ฒฝ ๋ณ์
| ์ด๋ฆ | ์ค๋ช | ๊ธฐ๋ณธ๊ฐ |
|---|---|---|
KIS_APP_KEY | KIS ์ฑํค | - |
KIS_APP_SECRET | KIS ์ํฌ๋ฆฟํค | - |
KIS_ACCOUNT_TYPE | REAL ๋๋ VIRTUAL | - |
KIS_CANO | ๊ณ์ข๋ฒํธ ์ 8์๋ฆฌ | - |
KIS_ACNT_PRDT_CD | ๊ณ์ข์ํ์ฝ๋ | 01 |
KIS_TOKEN_FILE | ํ ํฐ ์บ์ ํ์ผ | token.json |
KIS_ENABLE_TRADING | ์ฃผ๋ฌธ/์ ์ /์ทจ์ API ํ์ฑํ | ๋นํ์ฑ |
KIS_MCP_TOOLSET | MCP ๋๊ตฌ ๋
ธ์ถ ๋ฒ์ (full, catalog) | full |
KIS_MCP_LOG_LEVEL | ๋ก๊ทธ ๋ ๋ฒจ | INFO |
MCP_TYPE | stdio, sse, streamable-http | stdio |
MCP_HOST | HTTP/SSE host | 127.0.0.1 |
MCP_PORT | HTTP/SSE port | 8000 |
MCP_PATH | HTTP/SSE path | /mcp |
๊ฐ๋ฐ/๊ฒ์ฆ
uv run python -m compileall main.py server.py example.py tests
uv run python -m unittest discover -v
git diff --check
๋ผ์ด์ ์ค
MIT

