KRX 데이터 파이프라인 — MCP 서버로 KOSPI 시세·공시 자동 수집하기

미국 주식 데이터는 yfinance 한 줄이면 끝인데, KOSPI 종목 하나 받으려면 인증서·API 키·엔드포인트를 세 군데서 따로 관리해야 했습니다. 이 글을 읽고 나면 KRX 시세와 DART 공시를 하나의 MCP 서버로 통합해서 자동 수집하는 파이프라인을 만들 수 있게 됩니다. 데이터 출처가 흩어져 있어도 코드 한 곳에서 관리할 수 있죠.

준비물

시작하기 전에 다음 항목을 준비하세요.

• Node.js 18 이상 — MCP 서버가 Node.js 환경에서 돌아갑니다.
• KRX Open API 키 — KRX 마켓데이터 사이트에서 무료로 발급받을 수 있어요. 요금·플랜은 공식 페이지에서 확인하세요.
• DART API 키 — 금융감독원 전자공시 사이트에서 인증키를 신청합니다. 발급까지 하루 정도 걸렸어요.
• krx MCP 서버 패키지 — npm으로 설치 가능한 통합 MCP 서버입니다.

로컬 환경에 Node.js만 있으면 나머지는 설치 과정에서 함께 설정합니다.

KRX MCP 서버는 어떻게 설치하나요?

먼저 MCP 서버 패키지를 설치합니다. 터미널에서 다음 명령어를 실행하세요.

npm install -g @modelcontextprotocol/server-krx

설치가 끝나면 환경 변수를 설정해야 해요. .env 파일을 만들어서 발급받은 API 키를 넣습니다.

KRX_API_KEY=your_krx_api_key_here
DART_API_KEY=your_dart_api_key_here

이렇게 입력하면 서버가 시작될 때 자동으로 API 키를 읽어옵니다. 제 경우엔 이 단계를 건너뛰고 바로 CLI를 돌렸다가 401 에러가 3번 연속으로 떴어요. 환경 변수 설정을 먼저 끝내는 게 시간을 아끼는 길입니다.

서버가 제대로 설치됐는지 확인하려면 다음 명령어를 실행해 보세요.

krx-mcp --version

버전 정보가 출력되면 준비 완료입니다.

시세 데이터는 어떻게 수집하나요?

KRX API로 KOSPI·KOSDAQ 시세를 받아오는 단계입니다. MCP 서버는 CLI 명령어로도 쓸 수 있고, 코드에서 직접 호출할 수도 있어요. 먼저 CLI로 KOSPI 전체 종목의 현재가를 받아 보겠습니다.

krx-mcp get-market-data --market KOSPI --data-type snapshot

이 명령어를 실행하면 JSON 형태로 시세가 반환됩니다. 제가 오전 10시에 돌렸을 때는 종목 800개 정도가 2초 안에 다 내려왔어요. 각 종목마다 현재가·거래량·시가·고가·저가가 포함돼 있습니다.

코드에서 직접 쓰려면 이렇게 작성합니다.

import { KrxMcpClient } from '@modelcontextprotocol/server-krx';

const client = new KrxMcpClient({
  apiKey: process.env.KRX_API_KEY
});

const snapshot = await client.getMarketData({
  market: 'KOSPI',
  dataType: 'snapshot'
});

console.log(`받아온 종목 수: ${snapshot.stocks.length}`);

실행하면 받아온 종목 수: 823 같은 메시지가 뜹니다. 이 데이터를 JSON 파일로 저장하거나 데이터베이스에 넣으면 됩니다.

과거 데이터를 받으려면 dataType을 history로 바꾸고 날짜 범위를 지정하세요.

const history = await client.getMarketData({
  market: 'KOSDAQ',
  dataType: 'history',
  startDate: '2026-08-01',
  endDate: '2026-08-28'
});

이렇게 입력하면 8월 한 달 치 KOSDAQ 일봉 데이터가 내려옵니다.

공시 데이터는 어떻게 가져오나요?

DART에서 기업 공시를 받아옵니다. 공시는 정기보고서·공정공시·주요사항보고서로 나뉘며, 각 문서마다 접수번호가 부여되죠. 시세와 다른 점은 실시간이 아니라 공시 제출 시점 기준으로 조회한다는 겁니다.

기업 고유번호만 알면 CLI로 바로 조회할 수 있어요.

krx-mcp get-disclosure --corp-code 00126380 --count 10

최근 공시 10건이 1초 안에 내려왔습니다. 같은 작업을 코드로 하면 이렇게 됩니다.

const disclosures = await client.getDisclosure({
  corpCode: '00126380',
  count: 10
});

disclosures.forEach(doc => {
  console.log(`${doc.reportNm} - ${doc.receiptDt}`);
});

출력 예시입니다.

사업보고서 (2026.03) - 20260401
주요사항보고서(타법인주식및출자증권취득결정) - 20260328

특정 유형만 받고 싶다면 reportType 파라미터를 추가하세요. 사업보고서만 필요하면 reportType: 'A001'을 넣으면 됩니다.

데이터는 어디에 저장하는 게 좋나요?

수집한 데이터를 로컬 파일 시스템에 저장하는 방법입니다. JSON 파일로 저장하면 나중에 분석할 때 불러오기 쉬워요.

먼저 날짜별로 폴더를 나눠서 정리합니다.

import fs from 'fs/promises';
import path from 'path';

const today = new Date().toISOString().split('T')[0]; // 2026-08-28
const dataDir = path.join('./data', today);

await fs.mkdir(dataDir, { recursive: true });

시세 데이터를 저장할 때는 마켓과 데이터 타입을 파일명에 넣습니다.

const snapshotFile = path.join(dataDir, 'kospi-snapshot.json');
await fs.writeFile(snapshotFile, JSON.stringify(snapshot, null, 2));

console.log(`저장 완료: ${snapshotFile}`);

파일 하나당 2~3MB 정도였습니다.

공시 데이터도 같은 방식으로 저장하되, 기업 코드를 파일명에 넣어서 구분하세요.

const disclosureFile = path.join(dataDir, `disclosure-${corpCode}.json`);
await fs.writeFile(disclosureFile, JSON.stringify(disclosures, null, 2));

데이터베이스를 쓰려면 SQLite나 PostgreSQL에 테이블을 만들어서 넣으면 됩니다. 쿼리 속도가 중요하면 인덱스를 날짜와 종목 코드에 걸어 두는 게 좋아요.

흔한 실수와 해결법

API 키를 환경 변수로 안 넣고 직접 코드에 박았더니

하드코딩한 API 키가 Git에 커밋돼서 유출될 뻔했습니다. .env 파일을 만들고 .gitignore에 추가하세요. 저는 이 실수로 키를 재발급받느라 30분을 날렸어요.

타임아웃을 설정 안 했더니 공시 수집이 중간에 멈췄어요

DART API는 간혹 응답이 느릴 때가 있습니다. 클라이언트 옵션에 timeout: 10000 (10초)을 넣으니까 해결됐어요.

const client = new KrxMcpClient({
  apiKey: process.env.KRX_API_KEY,
  timeout: 10000
});

타임아웃 설정 전에는 5분 넘게 기다려도 응답이 안 와서 프로세스를 강제 종료한 적이 3번 있었습니다.

날짜 형식을 YYYY-MM-DD로 안 넣고 MM/DD/YYYY로 넣었더니 에러가 났어요

KRX API는 날짜를 YYYYMMDD 또는 YYYY-MM-DD 형식으로만 받습니다. 미국식 날짜를 넣으면 400 에러가 반환돼요. 입력하기 전에 Date 객체를 toISOString()으로 변환한 다음 split('T')[0]으로 날짜 부분만 추출하세요.

마무리

이제 KRX 시세와 DART 공시를 하나의 파이프라인으로 자동 수집할 수 있습니다. 다음 단계로는 수집한 데이터를 정규화해서 백테스트 프레임워크에 넣거나, 대시보드를 만들어서 실시간으로 모니터링하는 방법을 시도해 보세요. 데이터 수집이 자동화되면 전략 개발에 더 많은 시간을 쓸 수 있습니다.

자주 묻는 질문

Q. KRX API와 증권사 API의 차이는 무엇인가요?

A. KRX API는 거래소가 직접 제공하는 공개 마켓데이터입니다. 시세·지수·거래량 같은 시장 전체 데이터를 받을 수 있어요. 증권사 API는 계좌 조회·주문 같은 거래 기능까지 포함하지만, 종목별 데이터는 KRX API가 더 빠르고 안정적입니다.

Q. 실시간 데이터도 받을 수 있나요?

A. KRX Open API는 지연 데이터를 제공합니다. 보통 15분~20분 정도 지연돼요. 실시간이 필요하면 웹소켓 기반 증권사 API를 써야 하는데, 그건 별도 계좌 개설과 인증 절차가 필요합니다.

Q. 데이터는 어디에 저장하는 게 좋나요?

A. 분석 용도라면 로컬 JSON 파일이나 SQLite가 가볍고 관리하기 쉬워요. 장기 보관이나 쿼리 성능이 중요하면 PostgreSQL이나 TimescaleDB 같은 시계열 데이터베이스를 추천합니다. 제 경우엔 SQLite로 시작했다가 데이터가 1GB 넘어가면서 PostgreSQL로 옮겼습니다.

Q. API 호출 제한이 있나요?

A. KRX Open API는 무료 플랜 기준으로 분당 호출 제한이 있습니다. 정확한 제한은 API 키 발급 시 안내되는 문서를 확인하세요. DART API는 하루 10,000건까지 호출 가능하다고 명시돼 있어요.

Q. 여러 마켓을 한 번에 받으려면 어떻게 하나요?

A. KOSPI와 KOSDAQ을 각각 호출한 다음 결과를 배열로 합치면 됩니다. Promise.all()을 쓰면 병렬로 요청해서 시간을 절약할 수 있어요. 저는 이 방법으로 두 마켓 데이터를 3초 안에 다 받았습니다.