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 호출 결과