한국투자증권 MCP 연동 방법 — KIS Open API를 Claude에서 활용하기

Q: Mac과 Windows 모두 동일하게 설정하나요?

명령어 자체는 동일하지만 설정 파일 경로가 다릅니다. Mac은 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows는 %APPDATA%\Claude\claude_desktop_config.json을 수정합니다.

KIS Open API와 MCP를 연결하면 Claude가 한국투자증권 계좌 정보를 직접 조회하고 자연어 명령으로 시세·잔고·주문 흐름을 자동화할 수 있습니다. 이 가이드는 API 키 발급부터 Claude Desktop 설정, 실제 동작 확인까지 단계별로 완전히 해결합니다. KIS 전용 MCP 서버의 현황과 대안 서버 구성도 함께 다룹니다.

KIS Open API를 AI와 연결해야 하는 이유

한국투자증권의 KIS Open API는 국내 대표 증권 Open API 중 하나로, 국내주식 시세·계좌 잔고·주문·해외주식 조회 등 100종 이상의 엔드포인트를 REST 형태로 제공합니다. 그러나 API를 직접 호출하려면 OAuth2 토큰 관리, 파라미터 조합, 응답 파싱 작업이 필요해 개발 경험이 없으면 진입 장벽이 높습니다.

MCP(Model Context Protocol)를 경유하면 Claude나 Cursor가 자연어 지시를 받아 적절한 API 엔드포인트를 선택하고, 응답을 해석해 사람이 읽기 쉬운 형태로 돌려줍니다. 복잡한 파라미터 세팅 없이 “삼성전자 현재가 알려줘”라고 입력하면 AI가 알아서 처리합니다.

사용자 (자연어)
   │
   ▼
Claude / Cursor (LLM)
   │  MCP 프로토콜
   ▼
MCP 서버 (로컬 프로세스)
   │  REST 호출 + 토큰 관리
   ▼
KIS Open API (한국투자증권)
   │
   ▼
계좌 잔고 · 시세 · 주문 데이터

KIS Open API MCP 생태계 현황

2025년 기준으로 KIS Open API를 전담하는 성숙한 오픈소스 MCP 서버는 아직 공식 등록 단계에 있습니다. 현재 실전에서 활용 가능한 경로는 크게 두 가지입니다.

접근 방식	장점	단점
KIS 공식 Python SDK + 커스텀 MCP 서버	KIS 전체 API 지원, 최신 스펙 반영	직접 개발 필요
Korea Stock MCP (DART·KRX 연동)	즉시 설치 가능, 한국 주식 분석 지원	KIS 계좌 직접 조회 불가
DART MCP 서버 군	공시·재무제표 분석 특화	실시간 시세·주문 미지원

이 가이드에서는 즉시 사용 가능한 Korea Stock MCP로 한국 주식 AI 분석 환경을 먼저 구성한 뒤, KIS Open API 직접 연동을 위한 커스텀 서버 설정 방향도 안내합니다.

준비물

한국투자증권 계좌 (모의투자 계좌로도 가능)
KIS Open API 앱키·앱 시크릿 (아래 1단계 참고)
Node.js 18 이상 (node -v로 확인)
Claude Desktop 또는 Cursor (MCP 지원 버전)

1단계 — KIS Open API 앱키 발급

한국투자증권 홈페이지에 로그인한 뒤 트레이딩 > Open API 메뉴로 이동합니다.
서비스 신청 버튼을 클릭하고 이용 약관에 동의합니다.
신청 완료 후 App Key와 App Secret이 발급됩니다. 화면에서 복사해 안전한 곳에 저장합니다.
모의투자 환경을 사용하려면 같은 화면에서 ‘모의투자 신청’을 별도로 진행합니다. 모의투자용 키는 실거래 키와 구분되어 발급됩니다.

앱키는 외부에 노출되지 않도록 주의하세요. 설정 파일을 공개 저장소에 올릴 때는 반드시 .gitignore에 추가하거나 환경 변수로 분리하세요.

2단계 — Korea Stock MCP 서버 설치 (즉시 활용 경로)

한국 주식 AI 분석을 빠르게 시작하려면 Korea Stock MCP 서버를 먼저 설치합니다. 이 서버는 DART와 KRX 공식 API를 연결해 기업 재무 분석, 공시 검색, 시장 데이터 조회를 지원합니다.

Claude Desktop 설정 파일 위치

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

설정 파일을 열고 아래 내용을 추가합니다.

{
  "mcpServers": {
    "korea-stock": {
      "command": "npx",
      "args": ["-y", "korea-stock-mcp@latest"],
      "env": {
        "DART_API_KEY": "OpenDART에서_발급받은_인증키"
      }
    }
  }
}

DART API 키가 없다면 OpenDART에서 무료로 발급받을 수 있습니다.

Cursor 사용 시

Cursor의 경우 ~/.cursor/mcp.json 파일에 동일한 형식으로 추가합니다.

{
  "mcpServers": {
    "korea-stock": {
      "command": "npx",
      "args": ["-y", "korea-stock-mcp@latest"],
      "env": {
        "DART_API_KEY": "OpenDART에서_발급받은_인증키"
      }
    }
  }
}

3단계 — DART MCP 서버 추가 (재무·공시 분석 심화)

공시 분석과 재무제표 조회를 더 심층적으로 하려면 DART MCP 서버나 Korean DART MCP를 함께 등록할 수 있습니다. 금융감독원 OpenDART의 83개 API를 15개 MCP 도구로 정리한 버전입니다.

{
  "mcpServers": {
    "korea-stock": {
      "command": "npx",
      "args": ["-y", "korea-stock-mcp@latest"],
      "env": {
        "DART_API_KEY": "발급받은_DART_키"
      }
    },
    "korean-dart": {
      "command": "npx",
      "args": ["-y", "korean-dart-mcp"],
      "env": {
        "DART_API_KEY": "발급받은_DART_키"
      }
    }
  }
}

두 서버를 동시에 등록해도 충돌하지 않습니다. Claude가 요청 맥락에 따라 적절한 서버의 도구를 자동으로 선택합니다.

4단계 — 클라이언트 재시작 및 연결 확인

설정 파일 저장 후 Claude Desktop이나 Cursor를 완전히 종료하고 다시 실행합니다.

Claude Desktop에서 확인

# Claude Code CLI를 쓰는 경우 MCP 서버 목록 확인
/mcp

korea-stock 항목에 connected 상태가 표시되면 정상 연결입니다.

Cursor에서 확인

Settings → Features → MCP 탭에서 등록한 서버의 상태등이 초록색인지 확인합니다.

5단계 — 자연어 명령으로 동작 확인

아래 프롬프트를 그대로 입력해 MCP 도구가 실제로 동작하는지 테스트합니다.

“삼성전자 현재 주가와 시가총액을 알려줘”
“네이버의 최근 3년 매출 추이를 표로 정리해줘”
“코스피 시가총액 상위 10개 종목을 보여줘”
“카카오의 최근 공시 목록을 확인해줘”
“현대차와 기아의 영업이익을 비교 분석해줘”

Claude가 MCP 서버의 도구를 호출하면 화면에 도구 호출 내역이 표시됩니다. 결과 데이터가 정상적으로 돌아오면 연동 완료입니다.

KIS Open API 직접 연동 (커스텀 MCP 서버 구성)

KIS 계좌 잔고 조회, 실시간 주문 등 KIS 전용 기능이 필요하다면 커스텀 MCP 서버를 구성해야 합니다. KIS에서 공식 배포하는 Python SDK(python-kis)를 기반으로 MCP 서버를 래핑하는 방법이 현실적입니다.

기본 구성 방향

Claude (자연어 지시)
    │
    ▼
커스텀 MCP 서버 (Python/Node.js)
    │  python-kis 또는 직접 REST 호출
    ▼
KIS Open API
    │  앱키 + 토큰 인증
    ▼
계좌 잔고 · 주문 · 시세 응답

커스텀 서버 개발 시 고려 사항은 다음과 같습니다.

항목	내용
인증 방식	OAuth2 액세스 토큰 (유효기간 1일, 자동 갱신 구현 필요)
실거래 vs 모의	API 엔드포인트 도메인이 다름 (tr_id 헤더로 구분)
주의 사항	실거래 주문 기능은 잘못된 호출 시 실제 손실 발생 가능
레이트 리밋	초당 호출 횟수 제한 있음, 지수 백오프 구현 권장

흔한 오류와 해결 방법

npx 명령 실행 후 서버가 connected로 표시되지 않는 경우

Node.js 버전이 낮거나 네트워크 방화벽이 npx 다운로드를 차단하는 경우입니다. node -v로 버전(18 이상)을 확인하고, 사내 네트워크라면 IT팀에 npm 레지스트리 허용 여부를 문의하세요.

“DART_API_KEY is not set” 오류

설정 파일의 env 블록에 키를 넣었더라도 따옴표 누락·오탈자가 있으면 인식되지 않습니다. JSON 유효성 검사기(예: jsonlint.com)로 설정 파일 구문을 먼저 확인하세요.

KIS 토큰 만료 오류

KIS Open API 액세스 토큰은 하루 단위로 만료됩니다. 커스텀 MCP 서버를 사용하는 경우 서버 시작 시점에 토큰을 자동 재발급하는 로직을 구현해야 합니다.

모의투자 API 호출 시 에러 코드 반환

실거래 앱키로 모의투자 엔드포인트를 호출하거나 반대의 경우 오류가 발생합니다. 앱키 종류(실거래/모의투자)와 호출 도메인이 일치하는지 확인하세요.

자주 묻는 질문

KIS Open API 이용에 비용이 드나요?

KIS Open API 자체는 한국투자증권 계좌 보유자에게 무료로 제공됩니다. 단, 실거래 주문이 체결되면 일반 증권 거래 수수료가 발생합니다.

모의투자(종이 계좌)로도 MCP 테스트가 가능한가요?

네, KIS Open API는 모의투자 환경을 별도로 제공합니다. 앱키 발급 시 모의투자용 키를 선택하면 실제 계좌 없이도 주문·조회 API를 테스트할 수 있습니다.

Claude Desktop과 Cursor 중 어느 쪽을 추천하나요?

둘 다 MCP를 완전 지원합니다. Claude Desktop은 대화 흐름이 자연스러워 분석 중심 워크플로에 적합하고, Cursor는 코드 생성과 자동매매 스크립트 작성을 함께 진행할 때 편리합니다.

앱키와 앱 시크릿을 설정 파일에 직접 넣어도 안전한가요?

홈 디렉터리의 설정 파일은 본인 PC에서만 읽히므로 1인 개발 환경에서는 실용적인 방법입니다. 단, 파일을 Git 등에 커밋하거나 공유하면 키가 유출되므로 .gitignore 처리를 반드시 하세요.

KIS MCP 서버가 없으면 어떻게 하나요?

현재 커뮤니티가 공개한 KIS 전용 MCP 서버는 아직 성숙 단계입니다. 비슷한 목적으로 DART·KRX 데이터를 활용하는 Korea Stock MCP 서버를 먼저 사용해 보고, KIS 직접 연동은 공식 Open API SDK와 커스텀 MCP 서버를 조합하는 방법을 검토하세요.

Mac과 Windows 모두 동일하게 설정하나요?

명령어 자체는 동일하지만 설정 파일 경로가 다릅니다. Mac은 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows는 %APPDATA%\Claude\claude_desktop_config.json을 수정합니다.

다음 단계

KIS Open API와 AI를 연결하는 첫 환경이 구성됐다면, 이제 분석 범위를 넓혀볼 수 있습니다. 금융 카테고리에서 DART·KRX 기반 서버들을 추가로 등록하면 공시 검색, 재무 비교, 시장 동향 분석을 Claude 하나로 처리할 수 있습니다. 커스텀 KIS MCP 서버를 직접 개발했다면 MCP모아에 서버를 등록해 커뮤니티와 공유해 보세요.