korean-dart-mcp

# Korean DART MCP **OpenDART 83개 API를 15개 도구로.** 공시·재무·지분·XBRL + **버핏급 애널리스트 프레임(내부자 시그널·회계 리스크·퀄리티 체크리스트)** + **HWP/PDF 첨부 마크다운화**를 AI 어시스턴트에서 바로 사용. [](https://www.npmjs.com/package/korean-dart-mcp) [](https://modelcontextprotocol.io) [](LICENSE) > 금융감독원 [OpenDART](https://opendart.fss.or.kr/) 전자공시 기반 MCP 서버 + CLI. Claude Desktop, Cursor, Windsurf, Claude Code 등에서 바로 사용 가능. 자매 프로젝트: [korean-law-mcp](https://github.com/chrisryugj/korean-law-mcp) (법제처 41 API → 15 도구) English documentation → [README-EN.md](README-EN.md) --- ## ⚡ 30초 설치 — 한 줄로 끝 **macOS / Linux / Windows 공용**. Node.js 20.19+ 만 깔려있으면 됩니다. ```bash npx -y korean-dart-mcp setup ``` 대화형 마법사가 띄웁니다: 1. OpenDART 인증키 입력 (없으면 Enter — 나중에 설정 가능, [여기서 무료 발급](https://opendart.fss.or.kr/)) 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](#1-버핏식-5년-퀄리티-비교--자동-랭킹) 표 참고): 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](https://github.com/chrisryugj/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/chrisryugj/kordoc) 엔진으로 HWP/HWPX/PDF/DOCX/XLSX → 마크다운 변환 - 삼성전자 2.2MB PDF 사업보고서 → **921,998 자 마크다운 (3.7초)**. LLM 이 원문 전체를 컨텍스트로 읽고 분석 DART XML 원문(`download_document(format=markdown)`) 도 자체 파서로 heading/테이블 보존된 마크다운 변환. --- ## 왜 만들었나 한국 상장사 약 3,000개의 공시·재무가 [DART](https://dart.fss.or.kr) 한 곳에 모여 있지만, 개발자가 쓰려면 83개 엔드포인트를 직접 조합해야 합니다. 다행히 한국 개발자 생태계에는 [OpenDartReader](https://github.com/FinanceData/OpenDartReader)(438⭐) 와 [dart-fss](https://github.com/josw123/dart-fss)(364⭐) 라는 훌륭한 Python 래퍼가 있어, **엔드포인트 매핑·XBRL 파싱 노하우가 이미 정리돼 있습니다**. 이 프로젝트도 그 매핑을 상당 부분 그대로 수용했습니다. 이 프로젝트는 두 래퍼가 커버하지 못하는 **다른 레이어**를 목표로 합니다: - **pandas 생태계용** — OpenDartReader / dart-fss. DataFrame 으로 분석가가 직접 핸들링. - **LLM 네이티브용** — 이 프로젝트. raw 테이블을 **전문가가 쓰는 각도**(버핏 체크리스트·내부자 시그널·회계 리스크 스코어·공시 타임라인·마크다운 원문)로 한 번 더 정제해, AI 어시스턴트가 바로 스토리를 만들 수 있게 합니다. 둘은 **보완 관계**입니다. DataFrame 이 필요하면 Python 래퍼, AI 에이전트용 프레임이 필요하면 이 MCP. --- ## 설치 및 사용법 ### 0단계: API 키 발급 (무료, 1분) 모든 방법에 공통으로 **OpenDART 인증키**가 필요합니다. 1. [OpenDART 가입 페이지](https://opendart.fss.or.kr/uss/umt/cmm/EgovMberInsertView.do) 에서 회원가입 2. 로그인 후 [인증키 신청](https://opendart.fss.or.kr/mng/apiUsageStatusView.do) → 이메일로 **40자 인증키** 즉시 수신 3. 이 인증키를 아래 설정의 `DART_API_KEY` 에 넣습니다. 일 20,000건 무료. --- ### 방법 0: `setup` 마법사 (추천, 30초) ```bash 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` 가 뜨면**: 과거에 깨진 글로벌 설치가 남아있는 상태입니다. 아래 중 하나로 해결: > ```powershell > # 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](https://docs.claude.com/en/docs/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 이상](https://nodejs.org) 설치 (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` | **설정 내용:** ```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` 로 래핑하세요: > > ```json > { > "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: 내 컴퓨터에 직접 설치 (글로벌) ```bash npm install -g korean-dart-mcp ``` 설정 파일에 `command` 를 바꿔 등록: ```json { "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](https://github.com/chrisryugj/kordoc)) + ZIP 재귀 파싱 | --- ## 주요 특징 - **83 API → 15 도구** — OpenDART 전체(공시·재무·지분·주요사항·정기보고서·XBRL) 를 enum 압축. LLM 컨텍스트 8-10k → 6-8k 토큰 - **회사명 자동 해결** — "삼성전자" / "005930" / "00126380" 어느 형식이든 자동 변환 (SQLite FTS 선적재, 24h TTL) - **버핏급 애널리스트 프레임** — raw 테이블 위에 **시그널/스코어/체크리스트** 레이어를 얹어 AI 에이전트가 바로 쓰도록 가공 - **HWP/PDF 첨부 마크다운화** — [kordoc](https://github.com/chrisryugj/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 목록](https://opendart.fss.or.kr/intro/infoApiList.do) — 공식 83 엔드포인트 - [FinanceData/OpenDartReader](https://github.com/FinanceData/OpenDartReader) — pandas 래퍼 (438⭐) - [josw123/dart-fss](https://github.com/josw123/dart-fss) — XBRL 파싱 (364⭐) - 자매 프로젝트 [korean-law-mcp](https://github.com/chrisryugj/korean-law-mcp) — 법제처 MCP ## Star History <a href="https://www.star-history.com/?repos=chrisryugj%2Fkorean-dart-mcp&type=timeline&legend=bottom-right"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=chrisryugj/korean-dart-mcp&type=timeline&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=chrisryugj/korean-dart-mcp&type=timeline&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=chrisryugj/korean-dart-mcp&type=timeline&legend=top-left" /> </picture> </a> ## 라이선스 [MIT](./LICENSE) --- _{Made by 류주임 @ 광진구청 AI동호회 AI.Do}