Korean Dart

OpenDART 83개 API를 15개 도구로. 공시·재무·지분·XBRL + 버핏급 애널리스트 프레임(내부자 시그널·회계 리스크·퀄리티 체크리스트) + HWP/PDF 첨부 마크다운화를 AI 어시스턴트에서 바로 사용.

npm version MCP 1.27 License: MIT

금융감독원 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 엔진으로 HWP/HWPX/PDF/DOCX/XLSX → 마크다운 변환
• 삼성전자 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.

---

설치 및 사용법

0단계: API 키 발급 (무료, 1분)

모든 방법에 공통으로 OpenDART 인증키가 필요합니다.

1. OpenDART 가입 페이지 에서 회원가입
2. 로그인 후 인증키 신청 → 이메일로 40자 인증키 즉시 수신
3. 이 인증키를 아래 설정의 DART_API_KEY 에 넣습니다. 일 20,000건 무료.

---

방법 0: setup 마법사 (추천, 30초)

npx -y korean-dart-mcp setup

대화형으로 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 으로 설치하면 끝.

/plugin marketplace add chrisryugj/korean-dart-mcp
/plugin install korean-dart

설치 시 OpenDART 인증키 입력 프롬프트가 뜸 (한 번만). 이후 15개 DART 도구 자동 활성화.

---

방법 2: Claude Desktop / Cursor / Windsurf (수동 설정)

사전 준비: Node.js 20.19.0 이상 설치 (LTS 권장).

설정 파일에 아래 내용을 추가하세요 (YOUR_API_KEY 를 본인 키로 교체):

설정 파일 위치:

앱	Windows	Mac
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	프로젝트 .cursor/mcp.json	프로젝트 .cursor/mcp.json
Windsurf	프로젝트 .windsurf/mcp.json	프로젝트 .windsurf/mcp.json
Claude Code	~/.claude.json 또는 프로젝트 .mcp.json	~/.claude.json 또는 프로젝트 .mcp.json

설정 내용:

{
  "mcpServers": {
    "korean-dart": {
      "command": "npx",
      "args": ["-y", "korean-dart-mcp"],
      "env": {
        "DART_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

저장 후 앱을 재시작하면 15개 DART 도구가 활성화됩니다.

이미 다른 MCP 서버를 쓰고 있다면, "mcpServers": { ... } 안에 "korean-dart": { ... } 부분만 추가하세요.

⚠️ Windows 사용자: 위 설정으로 fail 이 뜨면 Claude Desktop 이 Windows PATH 의 .cmd 확장자를 해석하지 못해 npx 를 못 찾는 이슈입니다. 아래처럼 cmd /c 로 래핑하세요:

{
  "mcpServers": {
    "korean-dart": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "korean-dart-mcp"],
      "env": { "DART_API_KEY": "YOUR_API_KEY" }
    }
  }
}

그래도 안 되면: ① Node.js 20.19.0 이상 설치 여부 확인 (node --version), ② 방화벽이 opendart.fss.or.kr 차단하는지 확인, ③ 첫 기동 시 corp_code 덤프(11.6만건, 약 5-10초) 다운로드 중이니 10초 정도 기다린 후 재시도.

---

방법 3: 내 컴퓨터에 직접 설치 (글로벌)

npm install -g korean-dart-mcp

설정 파일에 command 를 바꿔 등록:

{
  "mcpServers": {
    "korean-dart": {
      "command": "korean-dart-mcp",
      "env": {
        "DART_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

첫 실행 시 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)

---

도구 구조 (15개)

기본 조회 (7)

도구	용도
resolve_corp_code	회사명 → corp_code (SQLite FTS 선적재, 전수 11.6만 건)
search_disclosures	공시 검색. page / preset(22종 자동필터) / all_pages 3모드 + 페이지 병렬화 + 90일 자동분할(v0.9)
get_company	기업 개황 (업종·대표자·설립일)
get_financials	재무정보. scope: summary(주요계정, 단일/다중사) / full(전체 BS/IS/CF, 단일사)
download_document	공시 원문 → format: markdown(DART XML 자체 파서) / raw / text
get_xbrl	XBRL. format: raw ZIP 해제(보안 가드) / markdown whitelist 50태그 / markdown_full taxonomy 전체(v0.9)
get_periodic_report	정기보고서 29 섹션 enum (배당·최대주주·감사인·보수·자금사용 등)

합성 래퍼 (4)

도구	용도
get_shareholders	지배구조 4섹션(최대주주·변동·소액주주·주식총수) 병렬 합성
get_executive_compensation	임원 보수 6섹션(전체·5억 이상·상위 5·미등기·주총승인·유형별)
get_major_holdings	5%룰(majorstock) + 임원·주요주주 본인 지분(elestock)
get_corporate_event	주요사항보고서 36 이벤트 enum + mode: single / timeline

애널리스트 프레임 (3 · 킬러)

도구	용도
insider_signal	임원 거래를 매수/매도 클러스터 시그널로 집계 (strong_buy_cluster 등)
disclosure_anomaly	정정공시·감사인 교체·비적정 의견·자본 스트레스 → 0-100 score + verdict
buffett_quality_snapshot	N년 ROE/부채/CAGR + 버핏 체크리스트 4종. corps 배열 지원 (1개=시계열, 2+=비교+랭킹)

원문 분석 (1)

도구	용도
get_attachments	공시 첨부 HWP/HWPX/PDF/DOCX/XLSX → 마크다운 (kordoc) + ZIP 재귀 파싱

---

주요 특징

• 83 API → 15 도구 — OpenDART 전체(공시·재무·지분·주요사항·정기보고서·XBRL) 를 enum 압축. LLM 컨텍스트 8-10k → 6-8k 토큰
• 회사명 자동 해결 — "삼성전자" / "005930" / "00126380" 어느 형식이든 자동 변환 (SQLite FTS 선적재, 24h TTL)
• 버핏급 애널리스트 프레임 — raw 테이블 위에 시그널/스코어/체크리스트 레이어를 얹어 AI 에이전트가 바로 쓰도록 가공
• HWP/PDF 첨부 마크다운화 — kordoc 엔진으로 공시 원문 본문을 LLM 이 직접 읽음 (2.2MB PDF → 3.7초)
• DART XML 자체 파서 — dart4.xsd 전용 마크업을 heading·테이블 보존된 마크다운으로 변환
• 페이지 병렬화 — search_disclosures 배치 모드 30-50초 → 17초 (2-3배)
• 22 프리셋 — 자기주식·CB/BW·합병·5%보유·정정·부실·소송 등 자주 쓰는 조합을 enum 으로
• XBRL 원본 노출 — 파싱 안 하고 해제 경로만 반환. Claude 가 직접 집계 가능
• OpenDartReader/dart-fss 호환 매핑 — 검증된 Python 래퍼들의 엔드포인트 매핑을 그대로 수용

---

참고

• OpenDART API 목록 — 공식 83 엔드포인트
• FinanceData/OpenDartReader — pandas 래퍼 (438⭐)
• josw123/dart-fss — XBRL 파싱 (364⭐)
• 자매 프로젝트 korean-law-mcp — 법제처 MCP

Star History

라이선스

MIT

---

_{Made by 류주임 @ 광진구청 AI동호회 AI.Do}