공매도 MCP 조회에 API 키가 반드시 필요한가요?

KRX 공개 데이터만 사용하는 서버라면 별도 API 키 없이 조회 가능한 경우도 있습니다. 다만 DART 공시 정보와 함께 활용하는 korea-stock-mcp 등은 OpenDART API 키가 필요합니다. 사용하는 서버의 저장소 README를 반드시 확인하세요.

공매도 잔고 데이터는 실시간인가요?

KRX가 제공하는 공매도 잔고 정보는 영업일 기준 전일 데이터로 공개됩니다. 실시간 체결 데이터가 아니므로, 당일 장중 데이터는 조회되지 않습니다.

MCP 서버 연결 후 Claude가 공매도 도구를 찾지 못하면 어떻게 하나요?

클라이언트를 완전히 종료하고 재시작하세요. Claude Code라면 /mcp 명령으로 서버 목록을 확인합니다. API 키 오류, Node.js 버전 미달, 설정 파일 JSON 문법 오류가 주요 원인입니다.

공매도 데이터 MCP를 DART 재무 분석과 함께 쓸 수 있나요?

네, 가능합니다. MCP 설정 파일에 공매도 데이터 서버와 DART MCP 서버를 함께 등록하면 Claude가 상황에 따라 두 서버를 함께 호출합니다. 예를 들어 공매도 잔고가 급증한 종목의 최근 공시를 자동으로 연결해 분석할 수 있습니다.

pykrx MCP로 공매도·외국인·기관 수급을 Claude에서 자연어로 분석하기

Q: Claude Code와 Claude Desktop 설정 파일 위치가 다른가요?

네, 다릅니다. Claude Code는 ~/.claude/settings.json이고, Claude Desktop은 macOS 기준 ~/Library/Application Support/Claude/claude_desktop_config.json입니다. 두 파일 모두 mcpServers 항목 구조는 동일합니다.

pykrx와 KRX 데이터를 MCP로 연결하면 Claude에서 종목별 공매도 잔고·거래량·비율은 물론, 외국인·기관 투자자별 매매동향까지 자연어 한 문장으로 조회할 수 있습니다. pykrx는 KRX 공개 데이터를 코드로 가져오는 라이브러리이고, MCP 서버가 이를 감싸면 파이썬을 몰라도 AI 대화만으로 수급·공매도 분석이 가능합니다. 이 글은 환경 설정, 설치, 로컬 서버 등록, 실전 프롬프트, 그리고 자주 발생하는 오류 해결법을 처음부터 끝까지 안내합니다.

공매도·수급 데이터를 MCP로 조회해야 하는 이유

공매도는 하락 압력을, 외국인·기관 수급은 단기 모멘텀과 중기 추세를 가늠하는 핵심 지표입니다. 한국거래소(KRX)는 종목별 공매도 거래량·비율과 투자자별 순매수/순매도 금액을 매일 공개하지만, 기존 방식은 불편했습니다. HTS에서 날짜별로 조회하거나, 파이썬 스크립트를 직접 짜거나, 유료 데이터 서비스에 의존해야 했습니다. Python 라이브러리인 pykrx는 KRX 공개 데이터를 코드 몇 줄로 가져올 수 있게 해주지만, 이를 직접 다루려면 Python 환경과 코딩 지식이 필요합니다.

**MCP(Model Context Protocol)**는 AI 클라이언트가 외부 도구를 표준화된 방식으로 호출하게 하는 오픈 프로토콜입니다. KRX 데이터를 MCP 서버로 감싸면 Claude나 Cursor가 직접 데이터를 호출해 대화 맥락 안에 올려줍니다. 결과는 자연어로 요약되고, 필요하면 표나 CSV로도 받을 수 있습니다. 이렇게 하면 투자자나 분석가가 Python 코드를 작성하지 않고도 공매도 현황과 수급 동향을 파악할 수 있습니다.

[사용자 자연어 질의]
        │
        ▼
[Claude / Cursor]  ─MCP 프로토콜─▶  [KRX MCP 서버]  ─pykrx/HTTP─▶  [KRX 공개 데이터]
        │                                   │
        ▼                                   ▼
[공매도·수급 분석 결과]      [공매도·투자자별 매매 JSON]

조회 가능한 데이터 구성 요소 이해하기

MCP로 조회할 수 있는 주요 지표를 미리 파악해 두면 프롬프트를 더 정확하게 작성할 수 있습니다.

공매도 지표

지표	설명	갱신 주기
공매도 거래량	당일 공매도로 체결된 주식 수	영업일
공매도 금액	공매도 체결 금액	영업일
공매도 잔고	아직 상환하지 않은 공매도 포지션 수량	영업일 다음 날
공매도 잔고 비율	상장 주식 수 대비 공매도 잔고 비율(%)	영업일 다음 날
공매도 거래 비율	전체 거래량 대비 공매도 거래 비율(%)	영업일

KRX가 제공하는 공매도 잔고는 전일 기준으로 공개됩니다. 당일 장중 실시간 데이터는 KRX 공개 API에서 제공하지 않으므로, 조회 결과는 항상 최소 하루 이전 데이터임을 염두에 두어야 합니다. 또한 pykrx는 장 마감 후 확정 데이터를 기준으로 하므로, 당일 데이터는 보통 평일 오후 6시 이후에 조회가 안정적입니다.

투자자별 수급 지표

pykrx의 투자자별 매매동향 함수는 외국인, 기관(기관합계), 개인은 물론 금융투자, 투신, 사모, 은행, 보험 등 세부 투자자 유형별 순매수/순매도 금액을 반환합니다. 대차잔고 등 일부 항목은 별도 API가 필요할 수 있습니다.

준비물

항목	필요 여부	비고
Node.js 18 이상	npx 방식 서버 사용 시 필수	nodejs.org에서 LTS 설치
Python 3.9 이상	로컬 pykrx 서버 사용 시 필수	3.11 권장
OpenDART API 키	korea-stock-mcp 사용 시 필수	무료 발급
Claude Code 또는 Claude Desktop	필수	MCP 지원 버전
Cursor	선택	MCP 지원 버전
인터넷 연결	필수	KRX 서버 접근용

pykrx는 KRX 공개 데이터를 가져오는 방식이므로 pykrx 자체에는 별도 API 키가 필요 없습니다. 단, 너무 짧은 간격으로 반복 요청하면 KRX 서버에서 일시 차단될 수 있으니 적정 간격을 유지하세요. DART 공시 정보를 함께 활용하는 서버(korea-stock-mcp 등)는 OpenDART API 키가 필요합니다.

두 가지 설치 경로 선택하기

KRX 데이터 MCP는 크게 두 가지 방식으로 쓸 수 있습니다.

경로 A — npx 기반 검증 서버: 별도 설치 없이 korea-stock-mcp처럼 공개된 서버를 실행합니다. KRX 주가·공매도와 DART 공시를 함께 다룰 때 편리합니다.
경로 B — 로컬 pykrx Python 서버: pykrx를 직접 설치하고 파이썬 MCP 서버 스크립트를 로컬 프로세스로 실행합니다. 투자자별 매매동향 등 pykrx 함수를 세밀하게 제어할 때 적합합니다.

아래 단계는 두 경로를 모두 다룹니다. 본인 목적에 맞게 선택하세요.

단계별 설치 방법

1단계 — 환경 확인 (Node.js / Python)

npx 방식 서버를 쓴다면 Node.js 버전을 확인합니다.

node --version

v18.0.0 이상이 출력되어야 합니다. 그보다 낮다면 nodejs.org에서 최신 LTS 버전을 설치하세요.

로컬 pykrx 서버를 쓴다면 Python에 pykrx를 설치하고 동작을 확인합니다.

pip install pykrx

설치 후 아래 한 줄로 KRX 접근이 정상인지 확인합니다.

python -c "from pykrx import stock; print(stock.get_market_ticker_list('20240101', market='KOSPI')[:3])"

정상이면 KOSPI 종목 코드 일부가 출력됩니다. 오류가 나면 Python 버전과 네트워크 연결을 먼저 확인하세요.

2단계 — OpenDART API 키 발급 (DART 연계 시)

KRX 데이터와 함께 DART 공시 정보를 활용하는 MCP 서버는 OpenDART API 키가 필요합니다.

opendart.fss.or.kr에 접속합니다.
우측 상단 회원가입을 클릭해 이메일 인증을 완료합니다.
로그인 후 인증키 신청/관리 메뉴를 클릭합니다.
이용 목적을 선택하고 신청하면 40자리 인증키가 즉시 발급됩니다.
발급된 키를 안전한 곳에 보관합니다. 이 키는 외부에 절대 노출하면 안 됩니다.

3단계(경로 A) — 한국 주식 MCP 서버 설치 및 설정

한국 주식 MCP 서버는 DART와 KRX API를 동시에 지원하는 서버입니다. npx 방식으로 별도 설치 없이 실행할 수 있습니다.

Claude Code 설정 (~/.claude/settings.json):

{
  "mcpServers": {
    "korea-stock-mcp": {
      "command": "npx",
      "args": ["-y", "korea-stock-mcp@latest"],
      "env": {
        "DART_API_KEY": "발급받은_40자리_키"
      }
    }
  }
}

Claude Desktop 설정 (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "korea-stock-mcp": {
      "command": "npx",
      "args": ["-y", "korea-stock-mcp@latest"],
      "env": {
        "DART_API_KEY": "발급받은_40자리_키"
      }
    }
  }
}

터미널에서 동작을 직접 확인하려면 아래 명령을 실행해 보세요.

npx -y korea-stock-mcp@latest

3단계(경로 B) — 로컬 pykrx MCP 서버 등록

pykrx 함수를 직접 다루는 로컬 파이썬 서버를 쓴다면, 설정 파일의 mcpServers 항목에 파이썬 스크립트 실행 블록을 추가합니다. 경로는 반드시 절대 경로로 입력하세요. 상대 경로는 클라이언트가 인식하지 못할 수 있습니다.

{
  "mcpServers": {
    "pykrx": {
      "command": "python",
      "args": ["/절대경로/pykrx_mcp_server.py"],
      "env": {}
    }
  }
}

설정 파일 위치는 운영체제·클라이언트마다 다릅니다.

Claude Code: ~/.claude/settings.json
Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

연결에 성공하면 도구 목록에 get_investor_trading, get_shortselling 같은 pykrx 관련 함수가 표시됩니다. Claude Code에서는 --mcp-config 옵션으로도 서버를 연결할 수 있습니다.

4단계 — DART MCP 서버 추가 설정(선택)

공매도 급증 종목의 최근 공시를 함께 분석하고 싶다면 DART MCP 서버를 함께 등록할 수 있습니다. 먼저 저장소를 클론합니다.

git clone https://github.com/2geonhyup/dart-mcp ~/Downloads/dart-mcp

이후 설정 파일의 mcpServers 항목에 서버 블록을 추가합니다.

{
  "mcpServers": {
    "korea-stock-mcp": {
      "command": "npx",
      "args": ["-y", "korea-stock-mcp@latest"],
      "env": {
        "DART_API_KEY": "발급받은_40자리_키"
      }
    },
    "dart-mcp": {
      "command": "uv",
      "args": ["--directory", "/Users/사용자명/Downloads/dart-mcp", "run", "dart.py"],
      "env": {
        "DART_API_KEY": "발급받은_40자리_키"
      }
    }
  }
}

--directory 경로는 실제 클론한 위치로 변경해야 합니다. uv가 설치되어 있지 않다면 pip install uv 또는 공식 문서(docs.astral.sh/uv)를 참고하세요.

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

설정 파일을 저장한 뒤 AI 클라이언트를 완전히 종료하고 다시 시작합니다.

Claude Code: 터미널에서 /mcp 명령을 입력하면 등록된 서버 목록과 연결 상태가 표시됩니다. connected 표시가 나오면 정상입니다.
Claude Desktop: 채팅창 왼쪽 하단 MCP 아이콘(망치 모양)을 클릭해 등록된 도구 목록을 확인합니다.
Cursor: Settings → MCP 탭에서 서버 상태 표시등이 초록색인지 확인합니다.

6단계 — 공매도·수급 데이터 조회

연결이 확인되면 자연어로 바로 데이터를 조회할 수 있습니다. 아래 예시 프롬프트를 참고하세요.

삼성전자의 최근 5거래일 공매도 거래량과 잔고 비율을 날짜별로 표로 보여줘

삼성전자(005930) 2024년 8월 외국인 일별 순매수 금액 보여줘

실전 프롬프트 예시

KRX 데이터 MCP를 활용한 다양한 분석 질의 예시입니다.

공매도 분석

분석 목적	예시 프롬프트
종목별 공매도 현황	”삼성전자 공매도 잔고와 잔고 비율을 최근 1개월 기준으로 정리해줘”
공매도 급증 종목 탐색	”코스피 시가총액 상위 50개 종목 중 공매도 잔고 비율이 높은 종목 순위를 알려줘”
추이 분석	”SK하이닉스의 올해 공매도 거래량 추이와 주가 변동을 함께 비교 분석해줘”
섹터별 비교	”반도체 섹터 주요 종목들의 공매도 잔고를 비교해줘”
공시 연계 분석	”최근 공매도 잔고가 급증한 종목의 최근 공시 내용을 요약해줘”

외국인·기관 수급 분석

질의 유형	예시 질문	주요 반환 필드
외국인 순매수	”외국인 코스피 순매수 상위 20종목”	종목명, 순매수금액, 거래량
기관 매매동향	”기관 합계 코스닥 순매도 상위 10”	기관합계, 금융투자, 투신 등
공매도 현황	”현대차 공매도 비율 최근 20일”	공매도금액, 공매도비율
투자자 세분화	”삼성전자 개인·외국인·기관 3주간 추이”	외국인, 기관, 개인 각각

공매도 데이터와 DART 공시를 연결한 분석을 원한다면 두 서버를 함께 등록해야 합니다. 조회 결과를 파일로 남기고 싶다면 Claude에 “결과를 CSV로 저장해줘”라고 요청할 수 있는데, 파일 쓰기에는 파일시스템 MCP 서버가 함께 설정돼 있어야 합니다.

흔한 오류와 해결법

”서버가 연결되지 않습니다” / “cannot find module” 오류

가장 흔한 원인 세 가지와 해결 방법입니다.

클라이언트 재시작 누락: 설정 파일 변경 후 클라이언트를 트레이 아이콘까지 완전히 종료하고 다시 여세요.
Node.js 버전 미달: node --version 명령으로 18 이상인지 확인하세요. 구버전이면 nodejs.org에서 최신 LTS를 설치합니다.
설정 파일 JSON 문법 오류: 쉼표 누락이나 따옴표 불일치가 자주 발생합니다. VS Code나 온라인 JSON 검증 도구로 설정 파일을 확인하세요.

”No module named pykrx” 오류 (로컬 파이썬 서버)

클라이언트가 시스템 Python이 아닌 다른 환경을 바라볼 때 발생합니다. 설정 파일의 command를 pykrx가 설치된 가상환경의 파이썬 절대 경로로 변경하세요.

{
  "mcpServers": {
    "pykrx": {
      "command": "/Users/yourname/.venv/bin/python",
      "args": ["/절대경로/pykrx_mcp_server.py"]
    }
  }
}

API 키 인증 실패 오류

# 키 앞뒤의 공백·줄바꿈을 제거하고 다시 입력
# 올바른 예: "DART_API_KEY": "abcdef1234..."
# 잘못된 예: "DART_API_KEY": " abcdef1234..." (앞에 공백)

API 키를 복사·붙여넣기 할 때 앞뒤 공백이 포함되면 인증에 실패합니다. 키를 다시 복사해 공백 없이 입력하세요.

dart-mcp 실행 시 “uv not found” 오류

pip install uv
# 또는
curl -LsSf https://astral.sh/uv/install.sh | sh

uv 설치 후 터미널 또는 Claude Code를 재시작해 PATH를 갱신합니다.

KRX 데이터 조회 결과가 비어 있는 경우

KRX 데이터는 영업일 기준으로 제공됩니다. 주말이나 공휴일에 조회하면 결과가 없거나 최근 영업일 데이터가 반환될 수 있습니다. 당일 데이터를 오전에 조회해도 빈 결과가 나올 수 있는데, pykrx는 장 마감 후 확정 데이터를 제공하므로 평일 오후 6시 이후에 조회하거나 전일 날짜를 기준으로 질의하세요. 상장 폐지되거나 거래 정지된 종목은 데이터가 없을 수 있습니다.

타임아웃 오류

데이터 범위가 너무 크거나(1년 이상 일별 데이터) KRX 서버가 일시적으로 느릴 때 발생합니다. 조회 기간을 3개월 이하로 줄이거나, MCP 서버의 타임아웃 설정을 늘리세요.

공매도·수급 MCP와 DART MCP 함께 활용하기

공매도나 수급 데이터만으로는 투자 판단을 내리기 어렵습니다. 잔고가 급증한 종목의 재무 건전성, 최근 공시, 경영진 발언 등을 함께 살펴봐야 합니다. MCP의 장점은 여러 서버를 동시에 등록해 Claude가 상황에 따라 최적의 데이터 소스를 선택하게 할 수 있다는 점입니다.

아래 서버들을 함께 등록하면 공매도·수급 현황부터 재무 분석까지 하나의 대화 세션에서 처리할 수 있습니다.

서버	역할	설치 명령
한국 주식 MCP 서버	KRX 주가·공매도 데이터	`npx -y korea-stock-mcp@latest`
DART MCP 서버	전자공시·재무제표 (Python)	`uv run dart.py`
한국 DART MCP	OpenDART 83개 API (npx)	`npx -y korean-dart-mcp`

예를 들어 “외국인이 순매수하는데 영업이익도 늘고 있는 코스피 종목 찾아줘” 같은 복합 질의는 수급 데이터와 DART 재무 데이터를 동시에 등록해야 가능합니다. 자세한 DART MCP 활용법은 금융 카테고리 가이드 모음에서 확인할 수 있습니다.

자주 묻는 질문

pykrx는 무엇이고 MCP와 어떤 관계인가요?

pykrx는 한국거래소(KRX)의 공개 웹 데이터를 Python으로 쉽게 가져올 수 있는 오픈소스 라이브러리입니다. MCP 서버가 pykrx와 같이 KRX 데이터를 내부적으로 활용하면, Claude 같은 AI 클라이언트가 별도 코드 없이 자연어로 KRX 공매도·수급 데이터를 조회할 수 있게 됩니다.

API 키가 반드시 필요한가요?

pykrx 자체는 별도 API 키 없이 KRX 공개 데이터에 접근합니다. 다만 MCP 서버 구현에 따라 추가 인증이 필요할 수 있고, DART 공시 정보와 함께 활용하는 korea-stock-mcp 등은 OpenDART API 키가 필요합니다. 사용하는 서버의 저장소 README를 반드시 확인하세요.

공매도 데이터는 어떤 항목까지 조회 가능한가요?

pykrx를 통해 종목별 공매도 거래량, 공매도 금액, 공매도 비율(전체 거래 대비)을 날짜 범위로 조회할 수 있습니다. 공매도 잔고와 잔고 비율은 영업일 다음 날 기준으로 공개되며, 대차잔고 등 추가 항목은 별도 API가 필요합니다.

외국인·기관·개인 구분은 어떻게 되나요?

pykrx의 투자자별 매매동향 함수는 외국인, 기관(기관합계), 개인, 금융투자, 투신, 사모, 은행, 보험 등 세부 투자자 유형별 순매수/매도 금액을 반환합니다.

공매도·수급 데이터는 실시간인가요?

아닙니다. pykrx는 실시간 시세가 아닌 장 마감 후 확정 데이터를 기준으로 하며, KRX 공매도 잔고는 전일 데이터로 공개됩니다. 당일 데이터는 보통 평일 오후 6시 이후에 조회가 안정적입니다.

Claude Code와 Claude Desktop 중 어디서 쓰나요? 설정 파일 위치가 다른가요?

둘 다 MCP 서버를 지원합니다. 로컬 파이썬 프로세스를 실행하는 경우 데스크톱 환경 사용이 일반적이며, Claude Code에서는 --mcp-config 옵션으로 연결할 수 있습니다. 설정 파일 위치는 다릅니다. Claude Code는 ~/.claude/settings.json, Claude Desktop은 macOS 기준 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows는 %APPDATA%\Claude\claude_desktop_config.json입니다. 모두 mcpServers 항목 구조는 동일합니다.

MCP 서버 연결 후 Claude가 도구를 찾지 못하면 어떻게 하나요?

클라이언트를 완전히 종료하고 재시작하세요. Claude Code라면 /mcp 명령으로 서버 목록을 확인합니다. API 키 오류, Node.js/Python 버전 문제, 설정 파일 JSON 문법 오류가 주요 원인입니다.

조회한 데이터를 CSV로 저장할 수 있나요?

Claude에 “결과를 CSV로 저장해줘”라고 요청하면 MCP 서버가 반환한 데이터를 Claude가 파일로 작성해줍니다. 단, 파일 쓰기에는 파일시스템 MCP 서버가 함께 설정돼 있어야 합니다.

다음 단계

공매도·수급 데이터 MCP를 설정했다면 이제 한국 주식 분석 자동화의 핵심 인프라를 갖춘 것입니다. 한국 DART MCP와 한국 주식 MCP 서버를 함께 등록하면 공매도 현황, 외국인·기관 수급, 재무 건전성, 최신 공시를 하나의 대화에서 종합 분석할 수 있습니다. 직접 사용해보고 유용한 MCP 서버를 발견했다면 전체 서버 목록에서 더 많은 한국 특화 MCP 서버를 찾아보세요.

관련 서버 상세 정보는 아래에서 확인할 수 있습니다.