3줄 요약
- 키움증권이 2026년 9월 10일 AI 에이전트용 MCP 서버 2종과 클로드 코드 플러그인을 공개했습니다. 7월에 나온 샘플코드, CLI까지 합치면 개발도구는 넷입니다.
- 시세와 계좌는 앱 키만 넣으면 바로 조회할 수 있습니다. 주문 도구는 설치할 때 따로 켜야 생깁니다.
- 주문 도구를 켜면 주문이 나갈지는
confirm=true값 하나로 정해집니다. 이 값은 AI도 넣을 수 있어서, 마지막 확인은 쓰는 AI 도구의 승인 창에서 사람이 합니다.
키움증권이 9월 10일 AI 에이전트용 MCP 서버 두 개와 클로드 코드 플러그인을 내놓자 기사들은 주문에 "겹겹의 안전장치"가 있다고 썼습니다. 공식 깃허브의 코드와 설치 가이드를 읽어 보니 그 안전장치의 절반은 MCP 서버가 아니라 같이 나온 플러그인에 있었습니다. 그래서 키움이 막아 주는 부분과 쓰는 사람이 챙길 부분은 나눠서 봐야 합니다.
조회는 설치만 끝나면 바로 쓸 수 있습니다. 주문은 설치할 때 켜야 도구가 생기고, 켠 뒤에도 실제로 나갈지는 클로드 같은 AI 도구가 띄우는 승인 창에서 사람이 누르느냐에 달렸습니다. 승인을 자동으로 넘기는 설정이라면 이 확인 단계는 없습니다.
키움 AI 개발도구 4종, 샘플코드·CLI 다음은 MCP 서버와 플러그인
키움 AI 개발도구는 샘플코드, CLI, MCP 서버, AI 코딩도구용 플러그인 넷입니다. 샘플코드와 CLI가 먼저 나왔고 이번에 MCP 서버 두 개와 플러그인이 공개됐습니다. 키움증권이 AI 에이전트 전문기업 라이브데이터와 함께 만들어 9월 10일에 발표했습니다. MCP 서버와 플러그인은 7월에 예고했던 후속작입니다.
MCP는 AI가 외부 서비스를 도구처럼 불러 쓰게 해 주는 규격입니다. 이 서버를 붙이면 클로드가 키움 API를 직접 호출합니다. CLI는 터미널에 명령어를 쳐서 쓰는 프로그램이고, 플러그인은 클로드 코드에 기능을 더하는 확장입니다. 아래 표의 "키"는 키움이 발급하는 App Key입니다. 이게 있어야 내 계좌 데이터에 접근할 수 있습니다.
| 도구 | 하는 일 | 키 필요 여부 |
|---|---|---|
| 샘플코드 | API 337개 스펙과 파이썬 예제 362개(국내주식 226개, 미국주식 134개) | 필요 |
CLI (kwcli) | 터미널에서 시세·차트·계좌 조회와 주문. PyPI로 설치, 명령어는 kiwoomcli | 필요 |
| Spec MCP | 만들 기능을 말하면 맞는 API와 예제 코드를 찾아 AI에게 넘긴다 | 필요 없음 |
| Exec MCP | 조회를 실제로 실행한다. 주문 도구는 켜야 생긴다 | 필요 |
| 클로드 코드 플러그인 | 종목 조사, 시황, 계좌, 포트폴리오 진단, 주문 등 스킬 8개와 선택형 화면 | 필요 |
발표는 9월 10일이었지만 MCP 서버와 설치 번들은 8월 27일에 이미 공식 깃허브에 올라왔습니다. 그래서 발표 전부터 써 본 사람도 있었습니다. Exec MCP는 안에서 CLI를 그대로 부르기 때문에 CLI가 함께 설치되어 따로 깔 필요가 없습니다. 파이썬은 3.13 이상이어야 합니다.
키움 MCP 연결 직후 조회할 수 있는 것
연결한 직후에는 시세와 계좌를 조회할 수 있지만 주문은 할 수 없습니다. 기본으로 설치하면 주문 도구가 들어 있지 않습니다.Spec 서버는 키 없이 돌아가며 만들려는 기능에 맞는 API를 찾아 줍니다. 키움에 실제로 요청을 보내는 쪽은 Exec 서버입니다. 어느 서버를 쓸지는 AI가 요청을 보고 고르므로 사용자가 따로 구분할 필요는 없습니다.
Exec 서버에 기본으로 생기는 도구는 셋입니다. 실행할 수 있는 명령 목록을 보여 주는 kiwoom_commands, 명령별 옵션을 알려 주는 kiwoom_help, 조회를 실행하는 kiwoom_query입니다. 조회 결과에 든 계좌번호는 자동으로 가린 뒤 AI에게 넘깁니다.
"보유 종목 오늘 등락 정리해줘"나 "삼성전자 일봉 최근 3개월 보여줘" 같은 요청은 설치 직후부터 AI가 처리합니다. "10주 사줘"는 주문 도구가 없어서 처리하지 못합니다.
클로드 데스크톱과 클로드 코드에서 키움증권 MCP 연결 방법
설치는 앱 키 받기, uv 깔기, 쓰는 도구에 등록하기 세 단계입니다. 설치 가이드를 보면 파이썬 3.13은 uv가 알아서 설치하고 관리합니다. 다만 클로드 데스크톱 번들을 쓸 때는 파이썬을 미리 깔아 둬야 합니다.- 키움증권 OpenAPI 포털에서 앱을 등록하고 App Key와 App Secret을 받습니다. 모의투자 키와 실전 키는 따로 나옵니다. 처음이라면 모의투자 키부터 받으세요.
uv를 설치합니다. uv는 파이썬 프로그램과 거기 필요한 부품을 받아서 실행해 주는 도구로, 두 서버 모두 uv 위에서 돌아갑니다. 저장소를 내려받아 설치한다면git도 있어야 합니다.
등록 방법은 도구마다 다릅니다. 공식 지원 도구는 클로드 데스크톱, 클로드 코드, 커서, 코덱스, 안티그래비티 다섯 가지입니다.
클로드 데스크톱은 설치 번들(.mcpb) 파일을 받아 더블클릭하면 설치 화면이 뜹니다. 설정 파일을 직접 고칠 필요는 없습니다. 대신 번들 안에 파이썬이 없습니다. 파이썬 3.13 이상과 uv가 깔려 있지 않으면 설치가 끝나도 오류 표시 없이 도구 목록이 비어 있을 수 있습니다. 첫 실행 때 의존성 파일을 약 140MB 받습니다. 리눅스는 지원하지 않습니다. 자동 업데이트도 없어서 새 버전이 나오면 번들을 다시 받아 덮어 설치해야 합니다.
9월 15일에는 1.0.1 번들이 올라왔습니다. 조회 결과의 단위나 표기에 주의할 점이 있는 명령에는 그 주의 문구를 붙여 AI에게 같이 넘기는 기능이 들어갔습니다. 이전 번들을 쓰고 있다면 새 파일로 덮어 설치하면 됩니다.
클로드 코드에서는 공식 저장소를 git clone으로 내려받아 폴더마다 의존성을 설치합니다. 등록은 공식 가이드에 나온 아래 두 줄 그대로 하면 됩니다.
claude mcp add kiwoom-spec -s user -- <UV_PATH> run --frozen --directory <REPO_PATH>/mcp_spec kiwoom-spec-mcp
claude mcp add kiwoom-exec -s user -e KIWOOM_MODE=demo -e APP_KEY=your_app_key -e APP_SECRET=your_app_secret -- <UV_PATH> run --frozen --directory <REPO_PATH>/mcp_exec kiwoom-exec-mcp둘째 줄 -e 뒤에는 환경변수가 옵니다. 프로그램에 설정값을 넘기는 방법으로, 여기서는 계좌 종류(KIWOOM_MODE=demo)와 키 두 개를 넘깁니다.
<UV_PATH>에는 uv만 쓰지 말고 전체 경로를 넣어야 합니다. 가이드에 따르면 클로드 데스크톱처럼 앱으로 실행되는 도구는 터미널의 PATH를 물려받지 않습니다. 그래서 터미널에서는 잘 돌다가 도구 안에서만 "command not found"로 멈추는 일이 흔합니다. 터미널에서 직접 조회도 하고 싶다면 CLI를 따로 설치합니다. 설치는 uv tool install kwcli, 명령어는 kiwoomcli입니다.
키움 MCP에서 주문이 실제로 나가려면
MCP 서버 코드가 주문 전송을 막는 조건은 주문 도구 켜기와confirm=true 두 가지입니다. 사람이 주문을 확인하는 단계는 키움 코드가 아니라 AI 도구의 승인 창에 있습니다.
주문 도구 두 개(미리보기, 전송)는 환경변수 KIWOOM_MCP_ALLOW_ORDERS가 정확히 "1"일 때만 등록됩니다. "true"나 "yes"를 넣으면 꺼진 것으로 봅니다. 이 값이 없으면 AI는 주문을 시도조차 할 수 없습니다.
주문 도구를 켜면 전송 도구는 confirm=true를 받아야 주문을 내보냅니다. 문제는 이 값을 누가 넣느냐입니다. 서버 코드의 설명문에는 이렇게 적혀 있습니다.
confirm can be set by the caller (an AI included). Human approval relies on the client's tool-execution approval or a future plugin hook. (kiwoom-exec-mcp server.py)
AI도 confirm=true를 넣을 수 있으니, 사람의 승인은 AI 도구가 띄우는 실행 승인 창에 맡겨진 셈입니다. 키움도 이를 알고 설치 가이드에 주문 도구를 켤 때는 "클라이언트의 도구 실행 자동 승인을 사용하지 않는 것이 전제"라고 적었습니다.
승인 창을 건너뛰는 설정이라면 이 관문은 사라집니다. 클로드 코드의 권한 확인 건너뛰기 모드가 대표적입니다. 에이전트 여러 개를 한꺼번에 돌리려고 이 모드를 켠 세션에 주문 도구를 켠 키움 서버가 붙어 있다고 해 봅시다. AI가 판단을 잘못하면 남는 안전장치는 계좌가 모의투자인지 실전인지 하나뿐입니다.
키움 플러그인과 MCP 서버, 주문 안전장치가 다른 점
기사에 나온 "미리보기 후 5분 만료"와 "실전투자 별도 승인"은 MCP 서버가 아니라 플러그인에 들어 있는 장치입니다. 여러 기사가 플러그인과 MCP 서버를 한 문단에 섞어 써서 MCP 서버에도 이 장치가 있는 것처럼 읽힙니다. 공식 코드로 나눠 보면 아래와 같습니다.
| 기사에 나온 안전장치 | 클로드 코드 플러그인 | MCP 서버 |
|---|---|---|
| 미리보기 후 5분 지나면 무효 | 있음. 주문 티켓이 기본 5분 뒤 만료 | 없음. 미리보기와 전송은 서로 이어지지 않는 별개 호출 |
| 확인한 주문은 한 번만 전송 | 있음. 전송하면 티켓이 사라짐 | 없음 |
| 실전투자는 별도 승인 | 있음. 실전이면 confirmReal이 추가로 필요 | 없음. 설치 때 정한 계좌 종류를 따른다 |
| 주문 기능 기본 꺼짐 | 꺼 두는 설정 대신 주문마다 사람이 확인 | 있음. ALLOW_ORDERS=1일 때만 주문 도구가 생김 |
| 인증 정보가 대화창을 거치지 않음 | 있음. kiwoomcli setup으로 넣은 키는 운영체제 자격 증명 저장소에 보관 | 있음. 다만 키가 설정 파일에 적힌다 |
플러그인에는 장치가 하나 더 있습니다. AI가 터미널에서 kiwoomcli 주문 명령에 --confirm을 붙여 직접 실행하려 하면 훅이 이를 막습니다. 이 훅은 클로드 코드에서만 동작합니다. 같은 플러그인이라도 코덱스나 안티그래비티에 설치하면 훅이 돌지 않습니다. 자동매매, 반복 주문, 조건부 자동 실행, 스케줄 주문은 지원 범위 밖이라며 플러그인이 거절합니다. 매매를 추천하지도 않습니다.
표 마지막 줄의 "설정 파일"도 조심할 부분입니다. 설치 번들은 보안 입력란으로 키를 받지만, 설치 가이드를 따라 설정하면 키를 설정 파일에 직접 적게 됩니다. 키는 대화 기록에 남지 않아도 홈 폴더의 설정 파일(클로드 코드는 ~/.claude.json)에는 남습니다. 그래서 가이드는 이 파일을 저장소에 올리거나 dotfiles로 동기화하지 말라고 따로 경고합니다.
키움 MCP를 원격(HTTP)으로 띄우면 계좌 기본값이 실전
원격으로 띄우면 계좌 종류를 지정하지 않은 요청이 실전 계좌로 갑니다.Exec 서버는 내 컴퓨터에서만 돌릴 수도 있고, 네트워크에 띄워 여러 사람이 접속하게 할 수도 있습니다. 뒤쪽을 HTTP 모드라고 합니다. 이때 키와 계좌 종류는 요청에 함께 오는 헤더로 받습니다. 로컬 번들은 계좌 종류 기본값이 모의투자인데 HTTP 모드에서 계좌 종류 헤더를 빼면 실전으로 처리합니다. 사내 서버에 올릴 계획이라면 요청마다 계좌 종류 헤더가 들어가도록 먼저 설정하세요.
해외 주문은 문서마다 설명이 다릅니다. README에는 국내와 해외 주문 모두 confirm=true로 전송된다고 나옵니다. 서버 코드 설명문에는 해외 주문 기능이 아직 미리보기 단계라 그동안은 CLI가 막는다고 적혀 있습니다. 미국주식 주문은 모의투자로 먼저 확인해 보세요.
키움 MCP를 처음 연결할 때 권하는 설정
처음에는 주문 도구 없이 조회 전용으로 붙이세요. 주문 도구가 없으면 AI가 저지를 수 있는 최악의 실수는 잘못된 조회입니다. 보유 종목과 시세 확인은 계좌번호가 가려진 채로 대화 한 번이면 끝납니다.
기업 API를 MCP로 감쌀 때 문제가 되는 곳은 대개 세 군데입니다. 키가 대화에 남는 문제, 조회와 주문 같은 쓰기 작업의 경계, 테스트 키와 실서버 키의 차이입니다. 키움은 셋 다 설계 단계에서 막았습니다. 서버 코드에 따르면 키는 환경변수나 요청 헤더로만 받고, 키를 인자로 받는 도구는 만들지 않습니다. 주문 도구는 기본 설치에서 아예 빼 두었고, 계좌 종류는 모의투자를 기본값으로 뒀습니다. ERP API를 MCP로 감싼 구조, 그리고 테스트 키와 실서버 키가 어떻게 다르게 움직이는지는 이 글에서 다뤘습니다.
함께 읽기이카운트 ERP 위에 AI를 얹었다
키움이 코드로 막지 못하는 곳은 사람이 누르는 승인 창 하나입니다. 이 부분은 쓰는 사람이 주문용 설정을 따로 두고 지켜야 합니다.
주문 도구를 켠 설정을 승인 건너뛰기 세션에 붙이지 마세요. 그러면 AI가 넣은 주문을 사람이 확인할 기회가 없어집니다.
키움 MCP 쓰기 전 체크리스트
| 구분 | 할 일 |
|---|---|
| 지금 | 모의투자 키로 조회 전용부터 설치한다. 주문 도구 설정값은 넣지 않는다 |
| 지금 | 키가 들어간 설정 파일을 저장소와 동기화 폴더에서 뺀다 |
| 지금 | 주문을 쓸 거라면 주문용 설정을 따로 만들고, 그 설정에서는 승인 건너뛰기 모드를 쓰지 않는다 |
| 기다릴 것 | 해외 주문을 어디까지 지원할지 확정되고 README와 코드 설명이 맞춰지는지 |
| 기다릴 것 | 서버 설명문에 나온 "향후 플러그인 훅" 수준의 승인 장치가 MCP 서버에도 생기는지 |
자주 묻는 질문
키움증권 MCP를 클로드 데스크톱에 설치했는데 도구가 안 보여요.
먼저 파이썬 3.13 이상과 uv가 컴퓨터에 깔려 있는지 확인하세요. 클로드 데스크톱에는 파이썬이 들어 있지 않아서, 둘이 없으면 설치가 끝나도 오류 표시 없이 도구 목록이 비어 있을 수 있습니다. 설치를 마쳤으면 앱을 완전히 종료한 뒤 다시 실행하세요.
모의투자로 먼저 해볼 수 있나요?
네, 할 수 있습니다. 설치 번들과 CLI 모두 모의투자가 기본값입니다. 다만 모의투자 키는 실전 키와 따로 발급받아야 하고, 모의투자 계좌로는 환율과 주문가능금액 조회 요청이 거절됩니다.
AI가 제 허락 없이 주문할 수 있나요?
기본 설치에는 주문 도구가 없어서 주문할 수 없습니다. 주문 도구를 켜면 confirm=true 값으로 전송 여부가 정해지는데, 이 값은 AI도 넣을 수 있습니다. 그래서 사람의 승인은 AI 도구가 띄우는 승인 창에 달려 있습니다. 그 창을 자동으로 넘기는 설정이라면 AI의 주문을 막을 장치가 없습니다.
계좌번호가 AI에게 그대로 보이나요?
아닙니다. 조회 결과에 든 계좌번호는 자동으로 가린 뒤 AI에게 넘깁니다. 앱 키와 시크릿도 도구 인자로 받지 않고 설정 파일이나 환경변수로만 받기 때문에 대화 기록에 남지 않습니다.
기사에 나온 5분 만료, 실전 별도 승인은 MCP에도 있나요?
아닙니다. 둘 다 클로드 코드 플러그인에 있는 안전장치입니다. MCP 서버에 있는 건 주문 도구 켜기 설정과 confirm=true 두 겹이고, 실전 계좌인지는 설치할 때 고른 계좌 종류를 따릅니다.
키움증권 MCP 신청 방법이 따로 있나요?
MCP 서버는 신청 없이 공식 깃허브에서 받아 씁니다. 신청이 필요한 건 App Key 발급입니다. 키움증권 OpenAPI 포털에 로그인해 OpenAPI 사용 신청을 하고 앱을 등록하면 App Key와 App Secret을 받을 수 있습니다. 모의투자용 키와 실전용 키는 각각 받아야 합니다.
키움 MCP 코드를 고쳐서 팀에 배포해도 되나요?
라이선스상 허락 없이는 할 수 없습니다. 라이선스는 키움증권 OpenAPI 이용 목적의 사용만 허락하고, 수정과 2차적 저작물 작성, 복제와 배포에는 회사의 사전 서면 동의를 받아야 한다고 적혀 있습니다.
