Korean DART MCP OpenDART 83개 API를 15개 도구로. 공시·재무·지분·XBRL + 버핏급 애널리스트 프레임(내부자 시그널·회계 리스크·퀄리티 체크리스트) + HWP/PDF 첨부 마크다운화를 AI 어시스턴트에서 바로 사용. 금융감독원 OpenDART 전자공시 기반 MCP 서버 + CLI. Claude Desktop, Cursor, Windsurf, Claude Code 등에서 바로 사용 가능. 자매 프로젝트: korean-law-mcp (법제처 41 API → 15 도구) English documentation → README-EN.md ⚡ 30초 설치 — 한 줄로 끝 macOS / Linux / Windows 공용. Node.js 20.19+ 만 깔려있으면 됩니다. 대화형 마법사가 띄웁니다: 1. OpenDART…
get_xbrl format="markdown_full" — presentation/calculation linkbase 를 파싱해 전체 계정 + 계층 구조 + 합산 검증. 기존 markdown 의 whitelist 50태그 대비 BS 50+ / IS 15+ / CF 10+ 전부 커버. 금융지주 DX prefix 등 업종별 택소노미 자동 대응. 6MB XBRL → ~30-60KB 마크다운.
search_disclosures 90일 자동분할 — corp_code 미지정 + 기간 90일 초과 시 자동으로 90일 청크 분할 (OpenDART “전체시장 3개월 제약” 우회). 최대 40 chunks(≈10년).
insider_signal / disclosure_anomalysummary_text — 한국어 자동 요약문 필드 추가. LLM 이 원시 테이블 뽑기 전 한 줄로 맥락 파악.
보안 하드닝 (v0.9.1) — ZIP slip / ZIP bomb 방어 공용 헬퍼, HTTPS 뷰어 스크래핑, chunks 상한, presentation 재귀 depth 가드, XBRL 파싱 경고 노출.
💡 주식에 관심 많은 일반인이 쓸 수 있는 5가지
증권사 앱만으론 아쉬운 개미 투자자 기준 킬러 유스케이스. Claude 에게 프롬프트로 그냥 말하면 됨.
1. 내 보유종목 “경영진 눈치게임”
"삼성전자 최근 1년 임원·대주주 매수/매도 보고 어때?"
→ insider_signal 이 매수 vs 매도 클러스터 시그널로 집계. 실측: 매수 2,429 vs 매도 43 → strong_buy_cluster (경영진이 자기 돈으로 사고 있음).
HTS 에선 공시 하나하나 뒤져야 알 수 있는 것을 한 줄 프롬프트로.
2. “이 회사 회계 뭐 수상한 거 없나”
"카카오 최근 3년 회계 리스크 점수 뽑아줘"
→ disclosure_anomaly 로 0-100 스코어 + verdict(clean/watch/warning/red_flag). 실측: 카카오 40점 warning — 정정공시 32.8% 가 임계 초과. 개인이 수동으로 확인 불가능한 리스크 플래그를 자동 탐지.
3. “사업보고서 300쪽 읽기 싫어”
"삼성전자 2023 사업보고서에서 '위험요소'·'주요 사업' 섹션 요약"
→ get_attachments(mode="extract") 가 PDF 2.2MB → 마크다운 92만 자로 변환 (3.7초). Claude 가 섹션별로 직접 검색·요약. 증권사 리포트 없이도 원본 읽기 가능.
4. “오늘 이런 공시 낸 회사 누구?”
"최근 30일 자기주식 취득 결정한 상장사 전부"
"최근 일주일 유상증자·CB 발행 공시 회사"
"최근 30일 합병·분할 결정 공시"
→ search_disclosures(preset=...) 22개 프리셋. 자기주식 취득 = 주가 부양 시그널 / 유상증자·CB = 희석 경계. 실측: 최근 30일 자기주식 취득 59건. HTS 에서 놓치는 배치 정보를 한 번에.
5. “A랑 B 중 뭐가 더 튼튼해”
"삼성전자 · SK하이닉스 · LG전자 5년 ROE·부채·성장성 비교"
→ buffett_quality_snapshot(corps=[...]) 이 5지표 자동 랭킹. 실측 (위 실전 시나리오 1 표 참고): SK하이닉스 3/4 체크 통과, 부채 안정성은 삼성 압도적. 종목 고를 때 감각 의존 대신 수치 근거.
이런 사람에게 딱
본인 보유 종목 5-20개 있고 분기·반기마다 공시 점검하는 중급 개미
뉴스 해석 말고 원본 공시 직접 보고 싶은 사람 (기자 편향 싫어하는 타입)
네이버 금융·HTS 정보 부족해서 답답한 사람
증권사 리포트 안 사고 직접 기업 분석하고 싶은 사람
이런 사람한텐 오버스펙
차트 보고 들어가는 단타 — 이 도구엔 차트·실시간 주가 없음
코스피 ETF 만 사는 장투 — 개별 종목 분석 필요 없음
Excel·Python 으로 DataFrame 돌리는 퀀트 — OpenDartReader·dart-fss 가 나음 (pandas 네이티브)
솔직한 진입 장벽
Claude Desktop / Cursor 설치 + OpenDART 키 발급 (10분, 무료, 일 20,000건)
ROE · CAGR · 부채비율 용어는 알아야 결과 이해 가능
Claude Pro 구독 $20/월 (대용량 PDF 요약엔 컨텍스트 넉넉한 상위 플랜이 편함)
이 도구는 리서치 보조용. 투자 판단은 본인이.
실전 시나리오 — 실제 API 호출 결과
아래 결과는 실제 DART API 를 때려 얻은 실측값. 전부 scripts/showcase-v0_9_1.mjs 로 재현 가능 (12/12 PASS).
PDF 첨부 2.2MB → 921,998자 마크다운 (3.7초). LLM 이 “위험요소” 섹션을 직접 검색해 요약 가능.
kordoc 엔진 (HWP/HWPX/PDF/DOCX/XLSX 통합) — OpenDartReader·dart-fss·기존 DART MCP 6종 어디에도 없는 기능.
기존 DART 도구와의 차별점
한국 DART 생태계 조사 결과 (2026-04-18 기준):
기능
OpenDartReader (438⭐, Python)
dart-fss (364⭐, Python)
hypn4/opendart-fss-mcp (85 도구)
RealYoungk/opendart-mcp (83 도구)
korean-dart-mcp (15 도구)
MCP 네이티브
❌
❌
✅
✅
✅
Node.js/TypeScript (npm)
❌
❌
❌
❌
✅ (유일)
엔드포인트 1:1 커버리지
대부분
공시+재무
85개 전부
83개 전부
83→15 enum 압축
회사명 자동 해결
부분
부분
✅ (오타·초성)
✅
✅ (SQLite FTS 선적재)
XBRL presentation/calculation linkbase
❌
ZIP만
ZIP+taxonomy
ZIP만
✅ 자동 markdown + 계산 검증
HWP/PDF 첨부 → 마크다운
❌
❌
❌
❌
✅ (유일, kordoc)
insider_signal 클러스터
❌
❌
❌
❌
✅ (유일)
disclosure_anomaly 0-100 스코어
❌
❌
❌
❌
✅ (유일)
buffett_quality_snapshot 체크리스트
❌
❌
❌
❌
✅ (유일)
90일 자동분할 · 페이지 병렬화
❌
❌
❌
❌
✅
ZIP slip/bomb 방어
n/a
n/a
❌
❌
✅
포지셔닝 한 줄
Python 래퍼(OpenDartReader · dart-fss) 는 “quant·백테스터가 Jupyter 에서 DataFrame 으로 쓰는 용”,
기존 Python DART MCP 6종은 “LLM 이 DART 원시 JSON 을 그대로 받아보는 용”,
이 프로젝트는 한국 DART 생태계에서 유일하게 LLM 네이티브로 설계된 Node.js MCP — 83 API 를 15 enum 으로 압축하고, XBRL 완전 파싱 · HWP/PDF 마크다운화 · 내부자/어노말리/버핏 애널리스트 프레임을 기본 탑재한 유일한 서버.
정직한 약점
엔드포인트 1:1 커버리지는 hypn4 (85 도구) / RealYoungk (83 도구) 가 더 넓음 — 희귀 엔드포인트 직접 호출이 필요하면 그쪽이 낫다. 이 프로젝트는 83→15 압축이라 자주 쓰는 조합을 제외한 엣지 엔드포인트는 제공하지 않음.
한국 DART MCP 시장 전체가 작아서 (최대 9⭐ · 2026-04 기준) 생태계 자체가 아직 초기.
v0.7.0 — LLM 네이티브 분석 레이어
DART 83 API 를 LLM 이 스토리로 해석 가능한 분석 프레임으로 가공해서 넘깁니다. 아래는 대표적인 네 가지 사용 시나리오.
버핏·그레이엄 관점 정량화
"삼성전자 임원 거래 최근 2년 매수/매도 클러스터 분석해줘"
→ insider_signal 한 번으로:
매수 보고 103건 (고유 임원 103명)
매도 보고 4건 (고유 임원 4명)
시그널: strong_buy_cluster (매수/매도 비율 25:1)
분기별 클러스터: 2024Q1 buy_cluster (n=42, net +380만주) → 2024Q2 buy_cluster (n=31, net +210만주) …
삼성전자 2.2MB PDF 사업보고서 → 921,998 자 마크다운 (3.7초). LLM 이 원문 전체를 컨텍스트로 읽고 분석
DART XML 원문(download_document(format=markdown)) 도 자체 파서로 heading/테이블 보존된 마크다운 변환.
왜 만들었나
한국 상장사 약 3,000개의 공시·재무가 DART 한 곳에 모여 있지만, 개발자가 쓰려면 83개 엔드포인트를 직접 조합해야 합니다. 다행히 한국 개발자 생태계에는 OpenDartReader(438⭐) 와 dart-fss(364⭐) 라는 훌륭한 Python 래퍼가 있어, 엔드포인트 매핑·XBRL 파싱 노하우가 이미 정리돼 있습니다. 이 프로젝트도 그 매핑을 상당 부분 그대로 수용했습니다.
이 프로젝트는 두 래퍼가 커버하지 못하는 다른 레이어를 목표로 합니다:
pandas 생태계용 — OpenDartReader / dart-fss. DataFrame 으로 분석가가 직접 핸들링.
LLM 네이티브용 — 이 프로젝트. raw 테이블을 전문가가 쓰는 각도(버핏 체크리스트·내부자 시그널·회계 리스크 스코어·공시 타임라인·마크다운 원문)로 한 번 더 정제해, AI 어시스턴트가 바로 스토리를 만들 수 있게 합니다.
둘은 보완 관계입니다. DataFrame 이 필요하면 Python 래퍼, AI 에이전트용 프레임이 필요하면 이 MCP.
대화형으로 API 키 입력 → 클라이언트 감지 → 설정 파일 자동 패치. macOS / Linux / Windows 공용. Windows 에선 cmd /c npx 래핑까지 자동 처리. 수동 JSON 편집 불필요.
지원: Claude Desktop / Claude Code / Cursor / VS Code / Windsurf / Gemini CLI / Zed / Antigravity.
MODULE_NOT_FOUND / Cannot find module ...\build\index.js 가 뜨면: 과거에 깨진 글로벌 설치가 남아있는 상태입니다. 아래 중 하나로 해결:
# A. 글로벌 구버전 제거 후 재시도 (Windows/Mac/Linux 공통)
npm uninstall -g korean-dart-mcp
npx -y korean-dart-mcp@latest setup
# B. 또는 글로벌 무시하고 항상 최신 받아오기
npx --yes --package=korean-dart-mcp@latest korean-dart-mcp setup
방법 1: Claude Code 플러그인 (한 줄 설치)
Claude Code 사용자는 marketplace 등록 후 /plugin 으로 설치하면 끝.
Windows 경로 주의: Claude Desktop 은 MSIX 패키지라 %APPDATA% 가 패키지 전용 위치로 리다이렉트됩니다. 앱이 실제로 읽는 파일은 %LOCALAPPDATA%\Packages\Claude_<publisher>\LocalCache\Roaming\Claude\ 아래에 있고, %APPDATA%\Claude\ 에 써 두면 앱이 읽지 않습니다. npx korean-dart-mcp setup 은 이 경로를 자동으로 찾습니다.
그래도 안 되면: ① Node.js 20.19.0 이상 설치 여부 확인 (node --version), ② 방화벽이 opendart.fss.or.kr 차단하는지 확인, ③ 첫 기동 시 corp_code 덤프(11.6만건, 약 5-10초) 다운로드 중이니 10초 정도 기다린 후 재시도.
첫 실행 시 OpenDART 가 제공하는 전체 기업 덤프(약 11.6만 건) 를 내려받아 ~/.korean-dart-mcp/corp_code.sqlite 에 FTS 인덱싱합니다 (약 5초, 24시간 TTL). 이후 회사명 / 종목코드 / corp_code 어느 형식으로 넘겨도 자동 해석됩니다.
API 키 전달 방법
방법
사용법
언제 쓰나
환경변수
DART_API_KEY=...
Claude Desktop 등 설정 파일
.env 파일
프로젝트 루트 .env
로컬 개발
사용 예시 — 킬러 프롬프트
기본 조회
"삼성전자 최근 분기 매출·영업이익, 전년 동기 대비 변화"
"최근 30일 자기주식 취득 결정한 상장사 전부"
"네이버 2023년 임원 보수 5억 이상 명단"
애널리스트 프레임
"삼성전자 임원 거래 최근 2년 매수/매도 클러스터 분석" → insider_signal
"카카오 최근 3년 회계 리스크 스코어 (정정·감사인·의견)" → disclosure_anomaly
"네이버 10년 버핏식 퀄리티 체크리스트" → buffett_quality_snapshot
"삼성·SK하이닉스·LG전자 5년 퀄리티 비교 + 순위" → buffett_quality_snapshot(corps=[...])
"LG에너지솔루션 2021년 이후 자본 이벤트 타임라인 전부" → get_corporate_event(mode=timeline)
원문 분석
"삼성전자 2023 사업보고서 PDF 본문에서 '위험요소' 섹션 요약" → get_attachments(mode=extract)
"삼성전자 자기주식 취득 결정 원본 XML 마크다운으로" → download_document(format=markdown)
배치 조회
"최근 7일 자기주식 취득 결정 상장사 전부" → search_disclosures(preset=treasury_buy)
"최근 30일 전환사채·신주인수권부사채 발행 공시" → search_disclosures(preset=cb_issue, days=30)
评论