Kiwoom MCP
ํค์์ฆ๊ถ REST API MCP ์๋ฒ - Claude Code ๋ฑ LLM์์ ํ๊ตญ ์ฃผ์ ์ ๋ณด ์กฐํ
Ask AI about Kiwoom MCP
Powered by Claude ยท Grounded in docs
I know everything about Kiwoom MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
kiwoom-mcp
ํค์์ฆ๊ถ REST API๋ฅผ Model Context Protocol (MCP) ๋๊ตฌ๋ก ๋ํํ ์๋ฒ์ ๋๋ค. Claude Code ๋ฑ MCP๋ฅผ ์ง์ํ๋ LLM ํด๋ผ์ด์ธํธ์์ ํ๊ตญ ์ฃผ์ ์ ๋ณด๋ฅผ ์ง์ ์กฐํํ ์ ์์ต๋๋ค.
ํ์ฌ ๋ฒ์ ์ ์กฐํ ์ ์ฉ์ ๋๋ค. ์ฃผ๋ฌธ(๋งค์/๋งค๋/์ทจ์) ๊ธฐ๋ฅ์ ํฌํจ๋์ด ์์ง ์์ต๋๋ค.
๋ฉด์ฑ ์กฐํญ (Disclaimer)
์ด ์ํํธ์จ์ด๋ฅผ ์ฌ์ฉํจ์ผ๋ก์จ ๋ฐ์ํ๋ ๋ชจ๋ ๊ฒฐ๊ณผ์ ๋ํ ์ฑ ์์ ์ ์ ์ผ๋ก ์ฌ์ฉ์ ๋ณธ์ธ์๊ฒ ์์ต๋๋ค.
- ์ด ํ๋ก์ ํธ๋ ๊ฐ์ธ ํ์ต ๋ฐ ํธ์ ๋ชฉ์ ์ผ๋ก ์ ์๋์์ผ๋ฉฐ, ํค์์ฆ๊ถ์ ๊ณต์ ์ ํ์ด ์๋๋๋ค.
- ํฌ์ ์กฐ์ธ, ๋งค๋งค ๊ถ์ , ๋๋ ์์ต ๋ณด์ฅ์ ํ์ง ์์ต๋๋ค.
- API ํธ์ถ๋ก ์ธํ ๊ณผ๊ธ, ๋ฐ์ดํฐ ์ค๋ฅ, ๊ณ์ข ์ ๋ณด ๋ ธ์ถ, ํ ํฐ ์ ์ถ ๋ฑ ์ด๋ ํ ์ง์ ์ ยท๊ฐ์ ์ ์ํด์ ๋ํด์๋ ์ ์์๋ ์ฑ ์์ง์ง ์์ต๋๋ค.
- ํค์์ฆ๊ถ OpenAPI ์ด์ฉ ์ฝ๊ด์ ๋ฐ๋์ ํ์ธํ๊ณ , ๋ณธ์ธ์ ์ฑ ์ ํ์ ์ฌ์ฉํ์ธ์.
- API ํค์ ์ํฌ๋ฆฟ ํค๋ ์ ๋ ๊ณต๊ฐ ์ ์ฅ์์ ์ปค๋ฐํ์ง ๋ง์ธ์. ํ๊ฒฝ๋ณ์ ๋๋
.envํ์ผ๋ก ๊ด๋ฆฌํ์ธ์. - ์ด ๋๊ตฌ๋ฅผ ํตํด ์กฐํํ ๋ฐ์ดํฐ์ ์ ํ์ฑ์ ๋ณด์ฅํ์ง ์์ต๋๋ค. ์ค์ ํฌ์ ํ๋จ์ ๋ฐ๋์ ๊ณต์ HTS/MTS๋ฅผ ํตํด ํ์ธํ์ธ์.
์ฌ์ ์ค๋น
- ํค์์ฆ๊ถ OpenAPI ์ ์ฒญ: ํค์ OpenAPI ํฌํธ์์ REST API ์ฌ์ฉ ์ ์ฒญ
- App Key / Secret Key ๋ฐ๊ธ: OpenAPI ํฌํธ์์ ๋ฐ๊ธ
- Node.js 18+ ์ค์น
์ ๊ณต ๋๊ตฌ
| ๋๊ตฌ๋ช | ์ค๋ช | ์ ๋ ฅ ํ๋ผ๋ฏธํฐ |
|---|---|---|
get_stock_price | ํ์ฌ๊ฐ ์กฐํ (์ข ๋ชฉ๋ช , ๋ฑ๋ฝ๋ฅ , PER, PBR ๋ฑ) | stockCode (6์๋ฆฌ) |
get_orderbook | ํธ๊ฐ ์กฐํ (๋งค๋/๋งค์ 1~10ํธ๊ฐ, ์๋) | stockCode |
get_daily_chart | ์ผ๋ด ์ฐจํธ (์/๊ณ /์ /์ข ๊ฐ, ๊ฑฐ๋๋) | stockCode, baseDate? (YYYYMMDD) |
get_investor_trend | ํฌ์์๋ณ ๋งค๋งค๋ํฅ (์ธ๊ตญ์ธ/๊ธฐ๊ด/๊ฐ์ธ ์๋งค์) | stockCode |
get_account_balance | ๊ณ์ขํ๊ฐํํฉ (์์๊ธ, ๋ณด์ ์ข ๋ชฉ, ์์ต๋ฅ ) | ์์ |
get_deposit | ์์๊ธ ์์ธ ์กฐํ (์ถ๊ธ๊ฐ๋ฅ, ์ฃผ๋ฌธ๊ฐ๋ฅ๊ธ์ก) | ์์ |
get_unfilled_orders | ๋ฏธ์ฒด๊ฒฐ ์ฃผ๋ฌธ ์กฐํ | ์์ |
get_filled_orders | ์ฒด๊ฒฐ ๋ด์ญ ์กฐํ | stockCode? (๋ฏธ์
๋ ฅ ์ ์ ์ฒด) |
์ค์น
git clone https://github.com/java-jaydev/kiwoom-mcp.git
cd kiwoom-mcp
pnpm install
pnpm run build
pnpm์ด ์์ผ๋ฉดnpm install && npm run build๋ก๋ ๊ฐ๋ฅํฉ๋๋ค.
ํ๊ฒฝ๋ณ์
| ๋ณ์๋ช | ํ์ | ์ค๋ช |
|---|---|---|
KIWOOM_APP_KEY | O | ํค์ OpenAPI App Key |
KIWOOM_SECRET_KEY | O | ํค์ OpenAPI Secret Key |
KIWOOM_API_BASE_URL | X | API ๋ฒ ์ด์ค URL (๊ธฐ๋ณธ๊ฐ: https://api.kiwoom.com) |
Claude Code ์ฐ๋
๋ฐฉ๋ฒ 1: CLI ๋ช ๋ น์ด (๊ถ์ฅ)
claude mcp add --transport stdio --scope user kiwoom \
--env KIWOOM_APP_KEY=<your-app-key> \
--env KIWOOM_SECRET_KEY=<your-secret-key> \
-- node /path/to/kiwoom-mcp/dist/index.js
๋ฐฉ๋ฒ 2: .mcp.json (ํ๋ก์ ํธ ์ค์ฝํ)
ํ๋ก์ ํธ ๋ฃจํธ์ .mcp.json ์์ฑ:
{
"mcpServers": {
"kiwoom": {
"type": "stdio",
"command": "node",
"args": ["/path/to/kiwoom-mcp/dist/index.js"],
"env": {
"KIWOOM_APP_KEY": "<your-app-key>",
"KIWOOM_SECRET_KEY": "<your-secret-key>"
}
}
}
}
.mcp.json์ API ํค๊ฐ ํฌํจ๋๋ฏ๋ก ๋ฐ๋์.gitignore์ ์ถ๊ฐํ์ธ์.
์ค์ ํ Claude Code๋ฅผ ์ฌ์์ํ๊ณ /mcp ๋ช
๋ น์ด๋ก ์๋ฒ ์ฐ๊ฒฐ์ ํ์ธํฉ๋๋ค.
๊ฒ์ฆ
# MCP Inspector๋ก ๋ก์ปฌ ํ
์คํธ
npx @modelcontextprotocol/inspector node dist/index.js
# Claude Code์์ ์ฐ๋ ํ์ธ
# /mcp ๋ช
๋ น์ด๋ก ์๋ฒ ์ํ ํ์ธ ํ "์ผ์ฑ์ ์ ํ์ฌ๊ฐ ์๋ ค์ค" ๋ฑ ์ง์
์ฃผ์์ฌํญ
- IP ์ ํ: ํค์ API ํ ํฐ์ ๋ฐ๊ธ๋ IP์์๋ง ์ ํจํฉ๋๋ค. ์๋ฒ์ ํด๋ผ์ด์ธํธ๊ฐ ๊ฐ์ IP์์ ์คํ๋์ด์ผ ํฉ๋๋ค.
- ํ ํฐ ๊ด๋ฆฌ: ํ ํฐ ์ ํจ๊ธฐ๊ฐ 24์๊ฐ, ๋ง๋ฃ 1์๊ฐ ์ ์๋ ๊ฐฑ์ ๋ฉ๋๋ค.
- ์ฅ ์ด์์๊ฐ: ์ฅ ๋ง๊ฐ ํ์๋ ์๊ฐ/๊ณ ๊ฐ/์ ๊ฐ๊ฐ 0์ผ๋ก ๋ฐํ๋ ์ ์์ต๋๋ค.
- ๊ฐ๊ฒฉ ๋ถํธ: ํค์ API ์๋ต์ ๊ฐ๊ฒฉ์๋
+/-๋ถํธ๊ฐ ๋ถ์ผ๋ฉฐ, ํ์ฌ๊ฐ ๋ฑ์ ์ ๋๊ฐ์ผ๋ก ๋ณํํ์ฌ ๋ฐํํฉ๋๋ค. - Rate Limit: ํค์ API์ ํธ์ถ ์ ํ์ ์ค์ํ์ธ์. ๊ณผ๋ํ ํธ์ถ์ ์ฐจ๋จ๋ ์ ์์ต๋๋ค.
๊ธฐ์ ์คํ
- TypeScript + Node.js (ES Module)
- @modelcontextprotocol/sdk
- Zod (์ ๋ ฅ ๊ฒ์ฆ)
- Stdio Transport
๋ผ์ด์ ์ค
MIT License
๊ธฐ์ฌ
์ด์์ PR์ ํ์ํฉ๋๋ค. ๋จ, API ํค๋ ์ํฌ๋ฆฟ ํค๊ฐ ํฌํจ๋ ์ปค๋ฐ์ ์ ๋ ํ์ง ๋ง์ธ์.
