실시간 KOSPI 지수를 Claude에서 바로 조회할 수 있나요?

MCP 서버가 KRX API를 통해 데이터를 가져오므로, KRX가 제공하는 시장 데이터의 범위와 갱신 주기에 따라 다릅니다. 실시간 체결 데이터보다는 당일 종가·거래량·시가총액 수준의 데이터 조회에 적합합니다. 정확한 제공 범위는 각 서버의 GitHub 저장소를 확인하세요.

Claude Code와 Cursor 중 어디에 설정해야 하나요?

둘 다 가능합니다. Claude Code는 ~/.claude/settings.json의 mcpServers 항목에, Cursor는 ~/.cursor/mcp.json에 서버 블록을 추가합니다. 두 환경에 동시에 설정해 사용할 수도 있습니다.

KOSPI·KOSDAQ MCP 연동 — Claude로 지수·수급·배당주까지 자동 분석

Q: pykrx와 MCP 서버의 차이는 무엇인가요?

pykrx는 Python 라이브러리로, Python 스크립트 안에서 직접 KRX 데이터를 가져올 때 사용합니다. MCP 서버는 이와 달리 Claude·Cursor 같은 AI 클라이언트가 자연어로 데이터를 요청할 수 있도록 표준화된 프로토콜 위에서 동작합니다. 두 방식은 상호 배타적이 아니며, MCP 서버가 내부적으로 KRX API를 호출하는 방식으로 유사한 데이터를 AI 대화에 통합합니다.

Q: MCP 서버를 연결했는데 도구가 보이지 않으면 어떻게 하나요?

클라이언트를 완전히 종료 후 재시작하고, Claude Code라면 /mcp 명령으로 서버 상태를 확인하세요. Node.js 버전이 낮거나 API 키에 공백이 섞인 경우가 흔한 원인입니다.

KOSPI·KOSDAQ 시장 데이터를 Claude에서 자연어로 바로 분석하고 싶다면, MCP(Model Context Protocol) 서버를 한 번만 설정하면 됩니다. KRX(한국거래소)와 DART API를 함께 지원하는 MCP 서버를 연결하면 Claude가 직접 시장 데이터를 가져와 분석해 줍니다. 이 글에서는 지수 조회뿐 아니라 외국인·기관 순매수 수급 분석과 고배당주 스크리닝까지, API 키 발급부터 설정 파일 작성, 실전 프롬프트, 흔한 함정까지 실제로 동작하는 수준으로 단계별로 안내합니다.

KOSPI·KOSDAQ 데이터를 MCP로 연결해야 하는 이유

한국 주식 시장 데이터를 분석하려면 전통적으로 KRX 정보데이터시스템 웹사이트를 직접 방문하거나, Python의 pykrx 같은 라이브러리를 코드로 작성해 가져와야 했습니다. 데이터를 받아도 해석은 별개 작업이고, 공시 데이터와 교차 분석하려면 또 다른 API 호출이 필요했습니다. 분석할 때마다 스크립트를 실행하고, 결과를 복사해 다시 AI에 붙여넣는 번거로운 과정이 반복됐습니다.

MCP는 AI 클라이언트(Claude, Cursor 등)가 외부 도구나 API를 표준화된 방식으로 직접 호출할 수 있게 해주는 오픈 프로토콜입니다. KOSPI·KOSDAQ 데이터를 제공하는 MCP 서버를 한 번 설정해두면, 이후에는 Claude에게 자연어로 “오늘 KOSPI 종가 알려줘”라고만 하면 됩니다. 스크립트 실행도, 복사·붙여넣기도 필요 없으며, 필터 조건을 바꾸고 싶으면 대화 흐름에서 바로 수정할 수 있습니다.

[사용자 자연어 질의]
        │
        ▼
[Claude / Cursor]  ──MCP 프로토콜──▶  [Korea Stock MCP 서버]
                                               │
                          ┌────────────────────┤
                          ▼                    ▼
                  [KRX API]           [DART OpenAPI]
                  (지수·거래량·수급)   (재무제표·배당공시)
                          │                    │
                          └────────┬───────────┘
                                   ▼
                        [Claude 자연어 분석 결과]

연동 가능한 한국 주식 MCP 서버 비교

현재 KOSPI·KOSDAQ을 포함한 한국 주식 데이터를 다루는 MCP 서버가 여러 개 공개되어 있습니다. 아래 표에서 특징을 비교합니다.

서버 이름	설치 방식	연동 API	API 키	GitHub
한국 주식 MCP 서버	npx	DART + KRX	필요	jjlabsio/korea-stock-mcp
DART MCP 서버	uvx (Python)	DART	필요	2geonhyup/dart-mcp
한국 DART MCP	npx	OpenDART	필요	chrisryugj/korean-dart-mcp

KOSPI·KOSDAQ 시장 지수·수급 데이터가 필요하다면 KRX API를 함께 지원하는 한국 주식 MCP 서버가 핵심 선택지입니다. DART만 지원하는 나머지 두 서버는 상장 기업의 재무제표·공시 분석에 특화되어 있으며, 지수·수급 데이터 자체는 KRX 연동이 있는 서버에서 다룰 수 있습니다.

DART MCP와 한국 DART MCP의 차이도 알아두면 좋습니다. DART MCP는 uv 기반으로 로컬 디렉터리에서 실행하며 기본 공시 조회에 특화돼 있고, 한국 DART MCP는 npx로 즉시 실행 가능하고 OpenDART 83개 API를 15개 도구로 압축해 재무·공시 분석을 폭넓게 지원합니다.

준비물 확인

설정을 시작하기 전에 아래 항목을 미리 준비합니다.

OpenDART API 키: opendart.fss.or.kr 무료 발급 (이메일 인증 필요)
Node.js 18 이상: node --version 으로 버전 확인
AI 클라이언트: Claude Code, Claude Desktop, 또는 Cursor (MCP 지원 버전)
터미널 접근 권한: 설정 파일을 편집할 수 있어야 합니다

단계별 설정 방법

1단계: OpenDART API 키 발급

한국 주식 MCP 서버들은 KRX와 DART API를 사용하며, 인증에 OpenDART 키가 필요합니다.

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

발급까지 보통 즉시~수 분 이내이며, 무료 플랜 기준 하루 10,000건 호출이 가능합니다. 발급받은 키는 외부에 공개하지 마세요. 환경 변수나 설정 파일 내 env 항목에만 넣어 사용하는 것이 안전합니다.

2단계: Node.js 설치 확인

npx 방식으로 서버를 실행하려면 Node.js 18 이상이 필요합니다. 터미널에서 아래 명령으로 버전을 확인합니다.

node --version

v18.x.x 이상이 출력되면 정상입니다. 설치되지 않았거나 구버전이라면 nodejs.org에서 최신 LTS 버전을 설치하세요.

설치를 확인했다면 아래 명령으로 서버가 정상 실행되는지 미리 테스트할 수 있습니다. 처음 실행 시 패키지를 자동으로 내려받으며, 에러 없이 진행되면 준비 완료입니다.

npx -y korea-stock-mcp@latest

3단계: MCP 설정 파일에 서버 추가

사용하는 클라이언트에 맞는 설정 파일에 서버 블록을 추가합니다.

Claude Code 환경 설정

Claude Code의 설정 파일(~/.claude/settings.json)을 텍스트 편집기로 열고 아래 블록을 추가합니다. 파일이 없으면 새로 만듭니다.

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

Claude Desktop 환경 설정

Claude Desktop을 사용한다면 운영체제별 설정 파일에 동일한 서버 블록을 추가합니다.

운영체제	설정 파일 경로
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

설정 파일이 없다면 새로 만들면 됩니다.

Cursor 환경 설정

Cursor를 사용한다면 ~/.cursor/mcp.json 파일에 동일한 서버 블록을 추가합니다.

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

이미 다른 MCP 서버가 등록되어 있다면 mcpServers 객체 안에 korea-stock-mcp 블록만 추가하면 됩니다.

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

설정 파일을 저장한 뒤 AI 클라이언트를 완전히 종료하고 다시 실행합니다. 시스템 트레이에 실행 중인 프로세스가 있다면 거기서도 종료해야 합니다.

Claude Code: 터미널에서 /mcp 명령을 입력하면 등록된 서버 목록이 표시되며, korea-stock-mcp 옆에 connected 상태가 보이면 정상입니다.
Claude Desktop: 채팅창 하단에 망치(도구) 아이콘이 표시되면 연결 성공입니다. “사용 가능한 MCP 도구 목록을 보여줘”라고 입력해 korea-stock-mcp 도구가 나타나는지 확인할 수도 있습니다.
Cursor: Settings(설정) → MCP 탭으로 이동해 서버 목록의 상태 표시등이 초록색인지 확인합니다.

5단계: 데이터 조회 테스트

연결이 완료되면 Claude에게 아래와 같이 자연어로 질의해 봅니다.

KOSPI 오늘 종가와 거래량을 알려줘.

서버가 정상적으로 동작하면 Claude가 KRX 데이터를 직접 가져와 답변합니다. 처음에는 간단한 질의로 연결을 확인하고, 이후 아래의 수급·배당 분석처럼 복합적인 요청으로 확장하는 것을 권장합니다.

실전 분석 프롬프트 예시

MCP 연결 후 아래와 같은 다양한 질의를 바로 사용할 수 있습니다.

목적	예시 프롬프트
시장 지수 조회	”오늘 KOSPI와 KOSDAQ 종가, 등락률을 비교해줘”
종목 검색	”코스피 시가총액 상위 10개 종목을 표로 정리해줘”
섹터 분석	”코스닥 반도체 관련 종목들의 오늘 등락 현황을 보여줘”
재무 연계 분석	”삼성전자 2023년 영업이익과 최근 주가 추이를 함께 분석해줘”
비교 분석	”현대차와 기아의 PER, PBR을 비교하고 저평가 여부를 판단해줘”

특히 DART와 KRX를 동시에 지원하는 korea-stock-mcp의 경우, 재무제표 데이터와 시장 가격 데이터를 하나의 대화에서 연계 분석할 수 있다는 점이 강점입니다.

활용 1: 외국인·기관 순매수 수급 분석 자동화

KOSPI·KOSDAQ 분석에서 빼놓을 수 없는 것이 투자자별 매매동향입니다. korea-stock-mcp는 KRX가 공식 집계하는 투자자별 순매수 데이터를 반환하므로, 자연어 한 문장으로 외국인·기관 수급 흐름을 정리할 수 있습니다.

투자 주체별 데이터 구조 이해

투자 주체	포함 범위
외국인	외국인 투자자 전체 (외국법인 포함)
기관	투신·보험·은행·증권·연기금 등 국내 기관 합산
개인	국내 개인 투자자 전체

순매수 = 매수 수량 - 매도 수량입니다. 양수이면 해당 주체가 해당 기간에 순매수, 음수이면 순매도를 의미합니다. 외국인과 기관이 동시에 대규모 순매수하는 종목은 일반적으로 수급이 강하다고 판단하지만, 이 데이터만으로 투자를 결정하는 것은 위험합니다. 반드시 재무·공시 데이터와 함께 종합적으로 검토하세요.

수급 분석 프롬프트 예시

특정 종목 투자 주체별 순매수 비교

삼성전자(005930) 최근 20거래일 외국인, 기관, 개인 순매수를 날짜별 표로 보여줘.

시장 전체 외국인 순매수 상위 종목

오늘 코스피 시장에서 외국인이 가장 많이 순매수한 종목 10개를 순서대로 알려줘.

기관 수급 집중 종목 스크리닝

최근 5거래일 동안 기관이 연속 순매수한 코스닥 종목이 있으면 알려줘.

수급이 강한 종목을 추렸다면, 같은 대화에서 DART 공시·재무제표와 교차 분석해 투자 판단 품질을 높일 수 있습니다.

오늘 외국인 순매수 상위 5개 종목의 최근 분기 실적과 공시 내용을 함께 정리해줘.

활용 2: 배당락일·배당수익률 기반 고배당주 스크리닝

HTS·MTS의 검색 필터는 배당수익률 단일 기준 정렬 정도만 지원하고, 배당락일 기준 정렬이나 배당 지속성 확인은 별도 작업이 필요합니다. MCP를 연결하면 KRX·DART 데이터를 기반으로 복합 조건의 고배당주 목록을 대화 한 번으로 뽑아낼 수 있습니다.

기본 배당 데이터 조회

이번 달 배당락일이 예정된 KOSPI 종목 중 배당수익률 3% 이상인 종목을
배당수익률 내림차순으로 정리해줘. 종목명, 배당락일, 예상 배당금,
시가 기준 배당수익률을 표로 보여줘.

스크리닝 조건 세분화

기본 조회 이후 조건을 좁혀 우량 배당주를 추립니다. DART 공시 데이터와 재무제표 정보가 함께 조회되므로 복합 조건 필터가 가능합니다.

위 결과에서 추가로:
- 최근 3년 연속 배당한 종목만
- 부채비율 200% 이하
- 시가총액 1,000억 원 이상
조건을 적용해서 다시 필터링해줘.

고배당주를 고를 때는 배당수익률뿐 아니라 배당성향(배당금/당기순이익), 배당 지속성(최근 3~5년 배당 이력), 부채비율, PBR 등을 함께 확인하는 것이 좋습니다. Claude에게 DART 공시 기반으로 이 지표들을 함께 조회해 달라고 요청할 수 있습니다.

참고로 모든 상장사가 배당을 지급하지는 않습니다. 배당 데이터가 조회되지 않는 종목은 배당 미지급 종목이거나 해당 분기 배당 공시가 아직 올라오지 않은 경우입니다. 공식 공시 일정은 DART에서 직접 확인하세요.

흔한 오류와 해결 방법

가장 흔한 원인과 해결 방법은 다음과 같습니다.

오류 증상	원인	해결 방법
”서버에 연결할 수 없습니다”	클라이언트 재시작 미완료	트레이 아이콘까지 완전 종료 후 재실행
”npx 명령을 찾을 수 없음”	Node.js 미설치 또는 구버전	`node --version` 확인 후 nodejs.org에서 LTS 설치
”API 키 인증 오류”	DART_API_KEY 값 오타·공백	발급받은 키를 따옴표 없이 다시 복사해 붙여넣기
”MCP 서버 연결 실패”	설정 파일 JSON 문법 오류	JSON 유효성 검사기로 콤마·괄호 누락 확인
데이터가 빈 값으로 반환	KRX 장 운영 시간 외·주말·공휴일 조회	”최근 거래일” 또는 특정 거래일 날짜를 명시해 재시도
오래된 데이터만 반환	캐시 문제	Claude 재시작 후 재시도

API 키 인증 실패 상세

DART_API_KEY 값을 확인할 때 키 앞뒤에 따옴표나 공백이 들어가지 않도록 주의하세요. 아래처럼 키만 정확히 입력해야 합니다.

"DART_API_KEY": "abc123def456..."

키를 재발급하려면 opendart.fss.or.kr의 인증키 관리 페이지를 방문하세요.

npx 실행 시 “permission denied” 오류

macOS에서 간혹 npx 실행 권한이 막히는 경우가 있습니다. 아래 명령으로 npx 캐시를 초기화하거나 Node.js를 재설치해 보세요.

npm cache clean --force

KRX 데이터 갱신 시점 주의

KRX 공식 API 특성상 투자자별 매매동향 등 일부 데이터는 전일 기준으로 제공됩니다. 장 마감 후 업데이트된 데이터를 다음날 오전부터 조회할 수 있으므로, 실시간 체결 데이터가 아니라는 점을 염두에 두고 프롬프트에 날짜를 명시하면 빈 값 오류를 줄일 수 있습니다.

결과를 파일로 저장하려면

수집·분석한 결과는 Claude에게 CSV 형식으로 출력해 달라고 요청하면 텍스트로 받을 수 있고, 이후 스프레드시트에 붙여 넣어 활용하면 됩니다. Claude Code 환경이라면 결과를 CSV나 마크다운 파일로 직접 저장하도록 추가 지시를 내릴 수 있습니다. Claude Desktop 단독 환경에서는 텍스트를 복사해 직접 저장하거나 Artifacts 기능으로 가공할 수 있습니다.

DART 공시 데이터도 함께 쓰려면

KOSPI·KOSDAQ 시장 데이터에 더해 기업 재무제표와 공시 분석이 필요하다면 DART 전용 MCP 서버를 추가로 등록할 수 있습니다.

DART MCP 서버(Python 기반)는 저장소를 클론해 로컬에서 실행합니다.

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

클론 후 설정 파일에 아래 블록을 추가합니다.

"dart-mcp": {
  "command": "uv",
  "args": ["--directory", "/Users/사용자명/Downloads/dart-mcp", "run", "dart.py"],
  "env": {
    "DART_API_KEY": "여기에_40자리_키_입력"
  }
}

한국 DART MCP는 npx 한 줄로 더 간편하게 설치됩니다.

npx -y korean-dart-mcp

설정 파일에서 mcpServers 객체 안에 여러 서버를 함께 등록하면 Claude가 맥락에 맞는 서버를 자동으로 선택해 호출합니다. 시장·수급 데이터는 KRX, 공시 데이터는 DART 서버로 분리해 두면 역할이 명확해집니다.

pykrx로 직접 다루는 방법 (참고)

MCP 서버는 내부적으로 KRX 데이터를 가져오지만, 동일한 데이터를 Python에서 직접 다루고 싶다면 pykrx 라이브러리를 쓸 수 있습니다. pykrx는 한국거래소 데이터를 파싱해 제공하는 오픈소스 라이브러리로, 별도 API 키 없이 일별 OHLCV·시가총액·거래대금 등을 가져옵니다. MCP가 무슨 데이터를 가져오는지 이해하는 데도 도움이 됩니다.

from pykrx import stock

# 삼성전자(005930) 2024년 1월 일별 OHLCV
df = stock.get_market_ohlcv("20240101", "20240131", "005930")
print(df.head())

market 파라미터로 시장 전체 시세도 받을 수 있습니다. "KOSPI" 또는 "KOSDAQ"을 지정합니다.

# 2024-01-15 코스피 전 종목 일별 시세
df_market = stock.get_market_ohlcv("20240115", market="KOSPI")

pykrx 사용 시 흔한 함정 두 가지를 기억하세요. 날짜는 반드시 "YYYYMMDD" 형식 문자열로 넣어야 하며("2024-01-15" 형태는 오류), 주말·공휴일을 지정하면 빈 DataFrame이 반환됩니다. 반환값은 pandas DataFrame이므로 to_csv()·to_excel()로 바로 저장할 수 있습니다.

자주 묻는 질문

KOSPI·KOSDAQ 데이터를 MCP로 가져오려면 API 키가 반드시 필요한가요?

네, korea-stock-mcp는 DART와 KRX API를 사용하므로 OpenDART API 키가 필요합니다. 키는 opendart.fss.or.kr에서 무료로 발급받을 수 있습니다.

KRX 데이터와 DART 공시 데이터를 동시에 쓸 수 있나요?

네, korea-stock-mcp 서버는 KRX(한국거래소) API와 DART(전자공시시스템) API를 함께 지원합니다. 하나의 서버로 지수·종목·수급 데이터와 재무공시 데이터를 모두 다룰 수 있습니다.

실시간 KOSPI 지수나 수급 데이터를 Claude에서 바로 조회할 수 있나요?

MCP 서버가 KRX API를 통해 데이터를 가져오므로, KRX가 제공하는 시장 데이터의 범위와 갱신 주기에 따라 다릅니다. 투자자별 매매동향 등 일부 데이터는 전일 기준으로 제공되어 다음날 오전부터 조회 가능하며, 실시간 체결 데이터보다는 당일 종가·거래량·시가총액 수준의 조회에 적합합니다. 정확한 제공 범위는 각 서버의 GitHub 저장소를 확인하세요.

외국인과 기관 순매수를 동시에 비교하는 쿼리가 가능한가요?

네, Claude에게 “삼성전자 최근 20거래일 외국인과 기관 순매수를 표로 보여줘”처럼 자연어로 요청하면 MCP 서버가 두 주체의 데이터를 함께 반환합니다.

고배당주 스크리닝 시 배당수익률 외에 어떤 지표를 함께 봐야 하나요?

배당성향(배당금/당기순이익), 배당 지속성(최근 3~5년 배당 이력), 부채비율, PBR 등을 함께 확인하는 게 좋습니다. Claude에게 DART 공시 기반으로 해당 지표들을 함께 조회해 달라고 요청할 수 있습니다.

pykrx와 MCP 서버의 차이는 무엇인가요?

pykrx는 Python 라이브러리로, 파이썬 스크립트 안에서 직접 KRX 데이터를 가져오고 결과 해석도 직접 해야 합니다. MCP 서버는 Claude·Cursor 같은 AI 클라이언트가 데이터 요청·집계·해석까지 자연어로 처리하도록 표준화된 프로토콜 위에서 동작합니다. 두 방식은 상호 배타적이 아니며, MCP 서버가 내부적으로 KRX API를 호출하는 방식으로 유사한 데이터를 AI 대화에 통합합니다.

Claude Code, Claude Desktop, Cursor 중 어디에 설정해야 하나요?

모두 가능합니다. Claude Code는 ~/.claude/settings.json, Claude Desktop은 claude_desktop_config.json(macOS는 ~/Library/Application Support/Claude/, Windows는 %APPDATA%\Claude\), Cursor는 ~/.cursor/mcp.json에 서버 블록을 추가합니다. 여러 환경에 동시에 설정해 사용할 수도 있습니다.

MCP 서버를 연결했는데 도구가 보이지 않으면 어떻게 하나요?

클라이언트를 트레이 아이콘까지 완전히 종료한 뒤 재시작하고, Claude Code라면 /mcp 명령으로 서버 상태를 확인하세요. 설정 파일의 JSON 문법 오류, 낮은 Node.js 버전, API 키에 섞인 공백이 흔한 원인입니다.

다음 단계

KOSPI·KOSDAQ MCP 연결을 완료했다면, 이제 Claude에서 지수·수급·배당 데이터를 자연어로 분석하는 환경이 갖춰진 것입니다. 더 심층적인 재무 분석을 원한다면 금융 카테고리의 다른 MCP 서버들도 함께 활용해 보세요. DART 공시 데이터와 KRX 시장 데이터를 조합하면 주가·수급·펀더멘털을 동시에 분석하는 강력한 AI 투자 분석 환경을 구성할 수 있습니다.

직접 사용해보고 유용한 MCP 서버를 발견했다면 서버 등록 페이지를 통해 MCP모아에 추가해 한국 커뮤니티와 공유해 보세요. 모든 MCP 서버 목록은 서버 전체 보기에서 확인할 수 있습니다.