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., "@kiwoom-mcp 삼성전자 현재가 확인하고 10주 시장가로 매수해줘"
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.
Claude Desktop에서 자연어로 키움증권 계좌를 제어하는 MCP 서버
키움증권 REST API와 Claude Desktop을 MCP(Model Context Protocol)로 연결하여, 자연어로 주식 조회/매매를 할 수 있습니다.
사용자: "삼성전자 현재가 알려줘"
Claude: 삼성전자(005930) 현재가 72,300원, 전일대비 +1,200원(+1.69%)...
사용자: "10주 시장가 매수해줘"
Claude: 삼성전자 10주 시장가 매수 주문 완료 (주문번호: 12345)openapi.kiwoom.com → 로그인 → API 사용신청
계좌 등록 + 본인 서버 IP 등록 (필수)
App Key 다운로드
모의투자 신청 (kiwoom.com → 모의/실전투자 → 상시모의투자)
Related MCP server: tossinvest-mcp
git clone https://github.com/YOUR_USERNAME/kiwoom-mcp.git
cd kiwoom-mcp
npm install
npm run build설정 파일 위치:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"kiwoom": {
"command": "node",
"args": ["/절대경로/kiwoom-mcp/dist/index.js"],
"env": {
"KIWOOM_APP_KEY": "...",
"KIWOOM_SECRET_KEY": "...",
"KIWOOM_ACCOUNT_NO": "계좌번호10자리",
"KIWOOM_IS_MOCK": "true"
}
}
}
}빌드 없이 개발 중 실행하려면:
"command": "npx", "args": ["tsx", "/경로/kiwoom-mcp/src/index.ts"]
키움 API는 등록된 IP에서만 호출 가능하므로, IP가 등록된 서버에 Docker로 배포하고 원격으로 연결할 수 있습니다.
.env 파일 생성KIWOOM_APP_KEY=발급받은_앱키
KIWOOM_SECRET_KEY=발급받은_시크릿키
KIWOOM_ACCOUNT_NO=계좌번호10자리
KIWOOM_IS_MOCK=true
MCP_TRANSPORT=http
MCP_PORT=3000
MCP_AUTH_TOKEN=여기에_토큰_입력토큰 생성:
openssl rand -hex 32
git clone https://github.com/YOUR_USERNAME/kiwoom-mcp.git
cd kiwoom-mcp
# .env 파일을 위에서 생성한 내용으로 작성
docker compose up -d --build{
"mcpServers": {
"kiwoom": {
"url": "http://서버IP:3000/mcp",
"headers": {
"Authorization": "Bearer 여기에_토큰_입력"
}
}
}
}변수 | 필수 | 설명 |
| O | 키움 OpenAPI 앱 키 |
| O | 키움 OpenAPI 시크릿 키 |
| O | 계좌번호 (10자리) |
| O | 모의투자 여부 ( |
| X | 전송 방식 ( |
| X | HTTP 모드 포트 (기본값: |
| HTTP 모드 시 O | Bearer 인증 토큰 ( |
Tool | 설명 |
| 보유 주식 목록, 평가금액, 수익률 |
| 종목별 비중/손익 분석 |
| 예수금, 출금/주문 가능금액 |
Tool | 설명 |
| 현재가, 등락률, 거래량, PER/PBR |
| 일봉 OHLCV 차트 (기간 지정) |
| 종목명 → 종목코드 검색 |
Tool | 설명 |
| 시장가/지정가 매수 |
| 시장가/지정가 매도 |
| 미체결 주문 목록 |
| 주문 취소 |
Tool | 설명 |
| 기간별 체결내역 |
| 종목별 실현손익, 승률 분석 |
"오늘 내 포트폴리오 현황 분석해줘"
"HD현대일렉트릭 현재가 알려주고 10주 매수해줘"
"이번달 거래 손익 분석해줘"
"미체결 주문 전부 취소해줘"반드시 모의투자(KIWOOM_IS_MOCK=true)에서 충분히 테스트한 후 실전 전환하세요
API 키를 공개 저장소에 절대 업로드하지 마세요
키움 REST API는 허용된 IP에서만 동작합니다
본 프로젝트는 키움증권 공식 프로젝트가 아닙니다
투자 손실에 대한 책임은 사용자 본인에게 있습니다
MIT - 투자 손실에 대한 책임은 지지 않습니다.
원주문번호로 미체결 주문을 취소합니다. 수량을 0으로 입력하면 잔량 전부 취소
Inputs: original_order_no (required), stock_code (required), quantity (required), account_no.
보유 주식 목록, 현재가, 매입가, 매입금액 등 계좌 잔고를 조회합니다
Inputs: account_no.
예수금, 증거금, 미수확보금 등 예수금 상세를 조회합니다
Inputs: account_no.
총평가금액, 총손익, 수익률 등 포트폴리오 전체 현황을 분석합니다
Inputs: account_no.
기준일자 기준 일봉 OHLCV 차트 데이터를 조회합니다 (최근 데이터부터 내림차순)
Inputs: stock_code (required), base_date.
종목의 현재가, 전일대비, 시가/고가/저가, 250일 고저, PER/PBR/EPS를 조회합니다
Inputs: stock_code (required).
당일 또는 특정 날짜의 매매일지(매수/매도 내역, 손익)를 조회합니다 (최근 2개월까지)
Inputs: base_date, account_no.
미체결 주문 목록을 조회합니다
Inputs: account_no.
주식 매수 주문을 실행합니다. 시장가 또는 지정가 매수를 지원합니다
Inputs: stock_code (required), quantity (required), price, order_type, +1 more.
주식 매도 주문을 실행합니다. 시장가 또는 지정가 매도를 지원합니다
Inputs: stock_code (required), quantity (required), price, order_type, +1 more.
종목코드로 종목명, 시장구분, 업종, 상장일 등 종목 기본 정보를 조회합니다
Inputs: stock_code (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 11 tools
Each tool has a clearly distinct purpose with no overlap: cancel_order cancels orders, get_account_balance retrieves account holdings, get_deposit_detail gets deposit details, get_portfolio_summary provides portfolio analysis, get_stock_chart fetches chart data, get_stock_price retrieves current stock metrics, get_trade_history shows trade history, get_unfilled_orders lists unfilled orders, place_buy_order executes buy orders, place_sell_order executes sell orders, and search_stock searches for stock information. The descriptions clearly differentiate their functions, eliminating any ambiguity.
All tool names follow a consistent verb_noun pattern using snake_case: get_account_balance, get_deposit_detail, get_portfolio_summary, get_stock_chart, get_stock_price, get_trade_history, get_unfilled_orders, place_buy_order, place_sell_order, search_stock, and cancel_order. The verbs (get, place, search, cancel) are appropriately matched to the nouns, creating a predictable and readable naming convention throughout the set.
With 11 tools, the count is well-scoped for a stock trading server, covering essential operations like account management, order placement, market data retrieval, and portfolio analysis. Each tool serves a specific, necessary function without redundancy, making the set comprehensive yet manageable for typical trading workflows.
The tool set provides complete coverage for stock trading and portfolio management: it includes CRUD-like operations (place/cancel orders, get trade history), account and portfolio analysis (balance, deposit, summary), market data access (stock price, chart, search), and order management (unfilled orders). There are no obvious gaps, as all core workflows from research to execution and monitoring are supported.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for stocksense-ai documentation, generated by doc2mcp.