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
대화형 마법사가 띄웁니다:
- OpenDART 인증키 입력 (없으면 Enter — 나중에 설정 가능, 여기서 무료 발급)
- 사용 중인 AI 클라이언트 번호 선택 (Claude Desktop / Cursor / Claude Code / Windsurf / VS Code / Gemini CLI / Zed / Antigravity — 설치된 건
[감지됨] 표시)
- 설정 파일 자동 패치 → 클라이언트 재시작
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년 내부자 거래 매수/매도 클러스터"
affaan-m