Kiwoom MCP

Kiwoom Securities REST API for Korean markets — 236 endpoints, streaming, gated order execution

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "kiwoom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "kiwoom-mcp"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

kiwoom-plugin

키움증권 REST API 236종(217 REST + 19 WebSocket)을 Claude Code에 연결하는 플러그인 모음입니다.

시세·차트·계좌·순위·실시간 스트리밍을 대화로 조회하고, 원한다면 주문까지 넣을 수 있습니다.

설치

Code

/plugin marketplace add gejyn14/kiwoom-plugin

그다음 둘 중 하나만 고릅니다.

Code

/plugin install kiwoom@kiwoom            # 조회 전용 (권장)
/plugin install kiwoom-trader@kiwoom     # 조회 + 주문

두 플러그인은 서로 대체하는 관계입니다. 같이 설치하면 같은 도구가 두 번 등록됩니다. 주문이 필요해지면 kiwoom을 제거하고 kiwoom-trader를 설치하세요.

MCP 서버는 uvx로 자동 실행되므로 별도 설치가 없습니다. uv만 있으면 됩니다.

왜 두 개인가

kiwoom에는 주문 도구가 아예 등록되지 않습니다. 설정으로 끄는 것이 아니라 도구 목록에 존재하지 않으므로, 모델이 실수로도 주문을 낼 수 없습니다.

안전 여부를 대화 중이 아니라 설치 시점에 정하는 편이 낫다고 보았습니다.

인증

kiwoom-cli와 같은 자격증명을 씁니다. 이미 설정했다면 추가 작업이 없습니다.

bash

uv tool install kiwoom-cli
kiwoom config setup      # appkey/secretkey를 OS 키체인에 저장
kiwoom auth login        # 토큰 발급

기본값은 모의투자(mock) 입니다. 실거래로 바꾸려면 kiwoom config set domain prod.

키체인이 없는 환경 (컨테이너·CI)

OS 키체인을 읽을 수 없는 곳에서는 호스트에서 발급한 토큰을 주입합니다.

server.ts

kiwoom auth login                          # 키체인 있는 호스트에서 발급
export KIWOOM_TOKEN='...'                   # 발급된 토큰
export KIWOOM_DOMAIN=mock                   # prod = 실계좌

KIWOOM_TOKEN은 키체인 토큰보다 우선하며, 만료되면 다시 발급해 넣어야 합니다.

할 수 있는 것

Code

삼성전자 지금 얼마야?
내 계좌 상태 정리해줘
오늘 거래량 상위 종목 보여줘
005930 최근 한 달 추세랑 외국인 수급 같이 봐줘
미체결 주문 있어?
내 조건식 돌려서 걸린 종목 알려줘
이번 달 실현손익 정리해줘

kiwoom-trader를 설치했다면:

Code

삼성전자 10주 71000원에 매수 주문 넣어줘

주문은 항상 사전점검 → 미리보기 → 확인 순서로 진행되며, 전송 전에 반드시 내용을 보여주고 승인을 받습니다.

포함된 스킬

스킬	언제
`stock-research`	종목 조사 — 시세, 차트, 수급을 하나로
`portfolio-review`	계좌·보유종목·평가손익·미체결 점검
`pnl-report`	실현손익·수익률을 기간별로 정리
`market-scan`	순위, 업종, 테마, 실시간 시세
`condition-search`	HTS에 저장한 조건식으로 종목 걸러내기
`kiwoom-setup`	인증·설정 진단 (연결이 안 될 때)
`place-order`	주문 절차 — `kiwoom-trader` 전용

안전 모델

조회 전용 플러그인에는 주문 도구가 등록되지 않습니다.
config set, auth login/logout 같은 로컬 설정 변경은 어느 플러그인에서도 차단됩니다. 모델이 도메인을 실거래로 바꾸거나 토큰을 폐기할 수 없습니다.
주문은 dry_run이 기본값입니다. 전송하려면 명시적으로 꺼야 합니다.
멱등키(client_order_id)로 재시도해도 중복 주문이 나가지 않습니다.
모든 응답에 meta.env가 실려 있어 모의(mock)인지 실거래(prod)인지 항상 확인할 수 있습니다.

구성

이 저장소가 MCP 관련 전부를 담습니다 — 플러그인, 스킬, 그리고 MCP 서버 본체.

Code

kiwoom-plugin/
├── plugins/kiwoom/           조회 전용 플러그인 + 스킬
├── plugins/kiwoom-trader/    조회 + 주문 플러그인 + 스킬
└── server/                   MCP 서버 (uvx로 직접 실행)

서버는 PyPI에 kiwoom-mcp로 게시되며, 플러그인이 uvx로 실행합니다. 안전장치(주문 확인, dry-run, 멱등키, envelope)는 kiwoom-cli의 것을 그대로 씁니다 — 서버는 kiwoom-cli를 감쌀 뿐 다시 구현하지 않습니다.

MCP 서버만 필요하면 플러그인 없이 직접 실행할 수 있습니다 (Claude Desktop, 다른 MCP 클라이언트 등):

bash

uvx kiwoom-mcp                  # 조회 전용
uvx kiwoom-mcp --allow-orders   # 조회 + 주문

면책

투자 판단과 그 결과는 사용자 본인의 책임입니다. 이 도구는 조회와 주문 실행을 도울 뿐 투자 조언을 하지 않습니다. 실거래 전에 반드시 모의투자로 충분히 검증하세요.

라이선스

Apache-2.0. kiwoom-cli는 별도의 소스 공개 라이선스를 따릅니다.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Kiwoom MCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "kiwoom-mcp": { "command": "npx", "args": ["-y", "kiwoom-mcp"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/kiwoom-mcp?style=directory)](https://allmcps.com/mcp/kiwoom-mcp)

HTML Embed

<a href="https://allmcps.com/mcp/kiwoom-mcp"><img src="https://allmcps.com/api/badge/kiwoom-mcp?style=directory" alt="Kiwoom MCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Kiwoom MCP →Install in Claude Desktop Install in Cursor Install in VS Code

Kiwoom MCP

Kiwoom Securities REST API for Korean markets — 236 endpoints, streaming, gated order execution

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "kiwoom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "kiwoom-mcp"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

kiwoom-plugin

키움증권 REST API 236종(217 REST + 19 WebSocket)을 Claude Code에 연결하는 플러그인 모음입니다.

시세·차트·계좌·순위·실시간 스트리밍을 대화로 조회하고, 원한다면 주문까지 넣을 수 있습니다.

설치

Code

/plugin marketplace add gejyn14/kiwoom-plugin

그다음 둘 중 하나만 고릅니다.

Code

/plugin install kiwoom@kiwoom            # 조회 전용 (권장)
/plugin install kiwoom-trader@kiwoom     # 조회 + 주문

두 플러그인은 서로 대체하는 관계입니다. 같이 설치하면 같은 도구가 두 번 등록됩니다. 주문이 필요해지면 kiwoom을 제거하고 kiwoom-trader를 설치하세요.

MCP 서버는 uvx로 자동 실행되므로 별도 설치가 없습니다. uv만 있으면 됩니다.

왜 두 개인가

안전 여부를 대화 중이 아니라 설치 시점에 정하는 편이 낫다고 보았습니다.

인증

kiwoom-cli와 같은 자격증명을 씁니다. 이미 설정했다면 추가 작업이 없습니다.

bash

uv tool install kiwoom-cli
kiwoom config setup      # appkey/secretkey를 OS 키체인에 저장
kiwoom auth login        # 토큰 발급

기본값은 모의투자(mock) 입니다. 실거래로 바꾸려면 kiwoom config set domain prod.

키체인이 없는 환경 (컨테이너·CI)

OS 키체인을 읽을 수 없는 곳에서는 호스트에서 발급한 토큰을 주입합니다.

server.ts

kiwoom auth login                          # 키체인 있는 호스트에서 발급
export KIWOOM_TOKEN='...'                   # 발급된 토큰
export KIWOOM_DOMAIN=mock                   # prod = 실계좌

KIWOOM_TOKEN은 키체인 토큰보다 우선하며, 만료되면 다시 발급해 넣어야 합니다.

할 수 있는 것

Code

삼성전자 지금 얼마야?
내 계좌 상태 정리해줘
오늘 거래량 상위 종목 보여줘
005930 최근 한 달 추세랑 외국인 수급 같이 봐줘
미체결 주문 있어?
내 조건식 돌려서 걸린 종목 알려줘
이번 달 실현손익 정리해줘

kiwoom-trader를 설치했다면:

Code

삼성전자 10주 71000원에 매수 주문 넣어줘

주문은 항상 사전점검 → 미리보기 → 확인 순서로 진행되며, 전송 전에 반드시 내용을 보여주고 승인을 받습니다.

포함된 스킬

스킬	언제
`stock-research`	종목 조사 — 시세, 차트, 수급을 하나로
`portfolio-review`	계좌·보유종목·평가손익·미체결 점검
`pnl-report`	실현손익·수익률을 기간별로 정리
`market-scan`	순위, 업종, 테마, 실시간 시세
`condition-search`	HTS에 저장한 조건식으로 종목 걸러내기
`kiwoom-setup`	인증·설정 진단 (연결이 안 될 때)
`place-order`	주문 절차 — `kiwoom-trader` 전용

안전 모델

조회 전용 플러그인에는 주문 도구가 등록되지 않습니다.
config set, auth login/logout 같은 로컬 설정 변경은 어느 플러그인에서도 차단됩니다. 모델이 도메인을 실거래로 바꾸거나 토큰을 폐기할 수 없습니다.
주문은 dry_run이 기본값입니다. 전송하려면 명시적으로 꺼야 합니다.
멱등키(client_order_id)로 재시도해도 중복 주문이 나가지 않습니다.
모든 응답에 meta.env가 실려 있어 모의(mock)인지 실거래(prod)인지 항상 확인할 수 있습니다.

구성

이 저장소가 MCP 관련 전부를 담습니다 — 플러그인, 스킬, 그리고 MCP 서버 본체.

Code

kiwoom-plugin/
├── plugins/kiwoom/           조회 전용 플러그인 + 스킬
├── plugins/kiwoom-trader/    조회 + 주문 플러그인 + 스킬
└── server/                   MCP 서버 (uvx로 직접 실행)

MCP 서버만 필요하면 플러그인 없이 직접 실행할 수 있습니다 (Claude Desktop, 다른 MCP 클라이언트 등):

bash

uvx kiwoom-mcp                  # 조회 전용
uvx kiwoom-mcp --allow-orders   # 조회 + 주문

면책

라이선스

Apache-2.0. kiwoom-cli는 별도의 소스 공개 라이선스를 따릅니다.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Kiwoom MCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "kiwoom-mcp": { "command": "npx", "args": ["-y", "kiwoom-mcp"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/kiwoom-mcp?style=directory)](https://allmcps.com/mcp/kiwoom-mcp)

HTML Embed

<a href="https://allmcps.com/mcp/kiwoom-mcp"><img src="https://allmcps.com/api/badge/kiwoom-mcp?style=directory" alt="Kiwoom MCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Kiwoom MCP →Install in Claude Desktop Install in Cursor Install in VS Code