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+ 만 깔려있으면 됩니다.

npx -y korean-dart-mcp setup

대화형 마법사가 띄웁니다:

1. OpenDART 인증키 입력 (없으면 Enter — 나중에 설정 가능, 여기서 무료 발급)
2. 사용 중인 AI 클라이언트 번호 선택 (Claude Desktop / Cursor / Claude Code / Windsurf / VS Code / Gemini CLI / Zed / Antigravity — 설치된 건 [감지됨] 표시)
3. 설정 파일 자동 패치 → 클라이언트 재시작

Windows 도 자동으로 cmd /c npx 래핑해줘서 npx not found 이슈 해결됨. 수동 JSON 편집 불필요.

수동 설정을 원하면 아래 설치 및 사용법 섹션 참고.

---

v0.9 — 무엇이 새로운가

• 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_anomaly summary_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).

1. 버핏식 5년 퀄리티 비교 + 자동 랭킹

프롬프트: "삼성전자·SK하이닉스·LG전자 최근 5년 퀄리티 지표 비교해줘"

→ buffett_quality_snapshot(corps=["삼성전자","SK하이닉스","LG전자"], years=5)

| 기업 | 평균 ROE | 최근 D/E | 매출 CAGR | 순이익 CAGR | 체크리스트 | |---|---:|---:|---:|---:|---:| | 삼성전자 | 10.39% | 29.94% | 4.51% | 3.17% | 1/4 | | SK하이닉스 | 12.86% | 45.95% | 22.6% | 45.37% | 3/4 | | LG전자 | 5.37% | 140.33% | 4.81% | -3.63% | 0/4 |

자동 생성 랭킹 (5지표별):

• ROE: SK하이닉스(12.86) > 삼성전자(10.39) > LG전자(5.37)
• 부채 안정성: 삼성전자(29.94) > SK하이닉스(45.95) > LG전자(140.33)
• 순이익 CAGR: SK하이닉스(45.37) > 삼성전자(3.17) > LG전자(-3.63)
• ROE 일관성 (stddev ↓): LG전자(2.09) > 삼성전자(3.91) > SK하이닉스(18.44)

2. 경영진이 본인 돈으로 매수하고 있는가 (insider_signal)

프롬프트: "삼성전자 최근 1년 내부자 거래 매수/매도 클러스터"

→ insider_signal(corp="삼성전자", start="2025-04-18", end="2026-04-18")

삼성전자: 2,473건 보고 (매수 2,429 / 매도 43).
고유 매수자 1,047명 vs 매도자 40명, 순매수 +2,302,375주.
→ strong_buy_cluster 시그널.
최강 클러스터: 2026Q1 (매수 985명/매도 18명).

버핏 철학의 "경영진이 본인 돈으로 매수하는가" 를 한 호출로 정량화. 최근 24:1 매수 우세.

3. 회계·거버넌스 리스크 스코어 (disclosure_anomaly)

프롬프트: "카카오 최근 3년 회계 리스크"

→ disclosure_anomaly(corp="카카오")

카카오 (2023-04~2026-04): ⚠️ 경고, 점수 40/100
- 정정공시 167/509건 (32.8%)  ← 임계(20%) 초과로 +30점
- 자본 스트레스 공시 5건       ← +10점
- verdict: warning

정정공시·감사인 교체·비적정 의견·자본 스트레스 4개 축을 0-100 스코어로 집계 + 개별 flag 의 evidence 구조화. LLM 은 스토리만 만들면 됨.

4. XBRL 전체 계정 + 계산 검증 (v0.9 markdown_full)

프롬프트: "삼성전자 2023 사업보고서 재무제표 전체 계정 뽑아줘"

→ get_xbrl(rcept_no="20240312000736", format="markdown_full")

기간: 당기 2023-12-31 / 전기 2022-12-31 / 전전기 2021-12-31
계정 수: BS 52행 · IS 18행 · CF 12행 (whitelist 모드의 17/13/7행 대비 3배)
마크다운 크기: 8,905자 (원본 XBRL 6MB → 99.85% 절감)
계산 검증: ✅ 모두 일치 (0 건 위반)
taxonomy roles: presentation 10개 · calculation 8개
소요: 615ms

계산 검증 자동화가 핵심 — calculation linkbase 의 summation-item 관계로 "부모=자식 합산"을 검증해서 공시 오기재를 즉시 탐지.

5. 업종별 택소노미 자동 대응 (금융지주)

프롬프트: "신한지주 최신 사업보고서 재무제표 전체"

→ 내부적으로 search_disclosures 로 rcept_no 찾고 → get_xbrl(format="markdown_full")

신한지주 2025 사업보고서 (rcept_no=20260318000826)
BS 44행 · IS 49행
계산 검증 위반: 3건 (금융업 특유 항목)
→ DX prefix (금융지주 전용) taxonomy 를 코드 변경 없이 자동 처리

dart-fss 도 XBRL ZIP 은 받지만 금융업 DX prefix 택소노미 자동 대응은 문서에 명시되어있지 않음. 업종별 커버리지는 이 MCP 의 강점.

6. 최근 30일 자기주식 취득 결정 상장사 전수

프롬프트: "최근 30일 자기주식 취득 결정한 상장사 전부"

→ search_disclosures(preset="treasury_buy", days=30, limit=500)

매칭 공시 59건 / 8페이지 병렬 수집 (17.5초)

최신 5건:
  2026-04-17 티플랙스 — 자기주식취득신탁계약해지결정
  2026-04-17 엠투엔 — 자기주식취득결정
  2026-04-17 PS일렉트로닉스 — 자기주식취득신탁계약해지결정
  2026-04-15 아세아 — 자기주식취득신탁계약해지결정
  2026-04-15 아세아시멘트 — 자기주식취득신탁계약해지결정

22개 프리셋이 pblntf_ty + report_nm 정규식을 자동 조립. LLM 이 DART 코드를 외울 필요 없음.

7. 전체시장 180일 공시 (90일 자동분할, v0.9)

프롬프트: "최근 6개월 사업보고서 낸 회사 전부"

→ search_disclosures(preset="annual_report", days=180)

자동분할: 3 chunks (DART '전체시장 3개월' 제약 자동 우회)
총 수집 6,000건 → 사업보고서 매칭 2,625건 (10.3초)

최신 3건:
  2026-01-09 미라셀 사업보고서 (2024.12)
  2026-01-08 케이원제15호판교위탁관리부동산투자회사 사업보고서 (2025.10)
  2026-01-08 삼성FN리츠 사업보고서 (2025.10)

8. 자본 이벤트 타임라인 (카카오 3년)

프롬프트: "카카오 최근 3년 자본 이벤트 전부"

→ get_corporate_event(corp="카카오", mode="timeline", start="2023-04-18", end="2026-04-18")

| 이벤트 유형 | 건수 | |---|---:| | 자기주식 처분 | 14 | | 감자 | 3 | | 합병 | 2 | | CB 발행 | 1 | | EB 발행 | 1 | | 합계 | 21 |

36개 이벤트 enum 을 한 번에 병렬 수집 → 날짜순 통합. LLM 이 "카카오가 최근 뭘 했는지" 즉시 파악.

9. 지분공시 통합 (5%룰 + 임원 지분)

프롬프트: "삼성전자 최근 3년 지분 변동 전부"

→ get_major_holdings(corp="삼성전자")

majorstock(5%룰): 41건 — 최근: 삼성물산 19.70% (2026-04-17)
elestock(임원·주요주주): 200건 반환 (2,615건 중 최근순)
기간: 2023-04-18 ~ 2026-04-18

두 엔드포인트(majorstock + elestock)를 한 호출로 합성 — Python 래퍼는 두 번 호출 + pandas merge 필요.

10. 단일기업 버핏 체크리스트 (근거 포함)

프롬프트: "삼성전자 6년 버핏 체크리스트"

→ buffett_quality_snapshot(corps=["삼성전자"], years=6)

삼성전자 2020~2025:
- ROE 평균 10.26% (min 4.26 / max 15.69 / stddev 3.58)
- D/E 최근 29.94% / 평균 31.11%
- 매출 CAGR 7.09% · 순이익 CAGR 11.35%

체크리스트 3/4:
  ❌ consistent_high_roe (모든 연도 ROE ≥ 15%)
  ✅ low_debt         (최근 부채비율 ≤ 100%)
  ✅ growing_revenue  (매출 CAGR ≥ 5%)
  ✅ growing_earnings (순이익 CAGR ≥ 5%)

11. 공시 원문 마크다운 (DART XML → MD)

프롬프트: "삼성전자 최근 자기주식 취득 결정 공시 원문"

→ search_disclosures(preset="treasury_buy") 로 rcept_no 찾고 → download_document(format="markdown")

원본: 2026-03-18 주요사항보고서(자기주식취득결정)
원본 XML 32,618자 → 마크다운 2,272자 변환 (93% 절감)
# 주요사항보고서(자기주식 취득 결정) / 삼성전자
## 자기주식 취득 결정
| 1. 취득예정주식(주) | 보통주식 | ...
| 3. 취득예상기간 | 시작일 | 2026년 03월 19일 |

DART 전용 XML(dart4.xsd)을 자체 파서로 heading·테이블 보존 마크다운으로.

12. 사업보고서 첨부 → 마크다운 본문

프롬프트: "삼성전자 2023 사업보고서 PDF 본문"

→ get_attachments(rcept_no="20240312000736", mode="extract", index=0)

• 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만주) ...

버핏 철학의 "경영진이 본인 돈으로 매수하는가?" 를 데이터로 굳혀 LLM 에 넘깁니다.

N년 퀄리티 체크리스트 + 피어 비교

"삼성전자·SK하이닉스·LG전자 5년 퀄리티 비교"

→ buffett_quality_snapshot(corps=[...]):

| 기업 | 평균 ROE | D/E | 매출 CAGR | 순이익 CAGR | 체크리스트 | |---|---:|---:|---:|---:|---:| | SK하이닉스 | 12.86% | 45.95% | 22.6% | 45.37% | 3/4 | | 삼성전자 | 10.39% | 29.94% | 4.51% | 3.17% | 1/4 | | LG전자 | 5.37% | 140.33% | 4.81% | -3.63% | 0/4 |

• ROE 랭킹: SK하이닉스 > 삼성전자 > LG전자
• 부채 안정성 랭킹: 삼성전자 > SK하이닉스 > LG전자
• ROE 일관성 (stddev): LG전자(2.09) > 삼성전자(3.91) > SK하이닉스(18.44)

회계·거버넌스 리스크 스코어

"카카오 최근 3년 회계 리스크 스코어"

→ disclosure_anomaly:

• 정정공시 비율, 감사인 교체 이력, 감사의견 비적정, 자본 스트레스 이벤트 빈도를 0-100 스코어로 집계
• verdict: clean / watch / warning / red_flag
• 각 flag 의 근거(evidence) 구조화

HWP/PDF 첨부를 LLM이 직접 읽음

"삼성전자 2023 사업보고서 본문에서 '위험요소' 섹션 요약해줘"

→ get_attachments(mode=extract):

• DART 뷰어 HTML 스크래핑으로 첨부 목록 조회
• [kordoc](https://github.com/aesthetic-legalism5470/kor