OpenDART MCP Server
한국 금융감독원 OpenDART API를 Claude에서 바로 사용할 수 있는 MCP(Model Context Protocol) 서버입니다.
API를 발급받아 Claude 커스텀 커넥터로 바로 연결할 수 있습니다.
Features
- Open DART API 전부 지원: Open DART에서 제공하는 API를 전부 지원합니다 (도구 85개).
- 2국면 스크리닝: 최대 500종목의 TTM 매출·영업이익 증가율을 서버에서 계산해 회사당 한 줄로 판정합니다 (
opendart_phase2_screen).
- 공시 원문 조회: 사업보고서 등 원문(document.xml)을 목차/섹션 단위로 나눠서 읽습니다.
- Vercel 배포: ngrok/터널링 없이 커스텀 커넥터로 바로 연결 가능합니다.
- URL 기반 API 키: 커넥터 URL에 키를 포함하여 설정 없이 즉시 사용 가능합니다.
- 마크다운 출력: Claude에서 깔끔하게 렌더링되는 테이블 형태로 출력합니다.
- Corp Code 캐싱: 11만+ 기업 목록을 인메모리 캐싱
기업 목록 갱신
회사 검색은 data/corp-codes.json(11만+ 기업의 이름 ↔ 고유번호 대조표)을 읽습니다.
스냅샷이라 갱신하지 않으면 신규 상장사를 찾지 못합니다.
매주 월요일 06:00(KST)에 GitHub Actions가 자동으로 갱신합니다
(.github/workflows/update-corp-codes.yml).
Actions 탭에서 수동 실행(Run workflow)도 가능합니다.
설정: 저장소 Settings → Secrets and variables → Actions에
OPENDART_API_KEY 시크릿을 등록해야 합니다.
로컬에서 갱신하려면:
OPENDART_API_KEY=your_key npm run update-corp-codes # 또는 .env에 키 저장
스크립트는 쓰기 전에 검증합니다. 기업 수가 비정상적으로 적거나, 이전보다 10% 이상 줄었거나,
종목코드 형식이 깨졌으면(예: 앞자리 0 탈락) 파일을 건드리지 않고 실패합니다.
Quick Start
1. OpenDART API 키 발급
OpenDART에서 회원가입 후 API 인증키를 발급받으세요.
2. Claude에 연결
- claude.ai 접속
- 사용자 지정 > 커넥터 > 사용자 지정 커넥터 추가
- URL 입력:
https://your-project.vercel.app/api/mcp?opendart_key=YOUR_API_KEY
- 연결 완료! 별도 설정 없이 바로 사용 가능
Tools
Config (2개)
| Tool | 설명 |
|---|
set_api_key | OpenDART API 키를 세션에 설정 |
get_api_key_status | API 키 설정 여부 확인 |
회사 검색 & 정보 (3개)
| Tool | 설명 |
|---|
opendart_search_company | 한글/영문 이름 또는 종목코드로 회사 검색 → corp_code 획득 |
opendart_get_company_info | 기업 개황 (대표이사, 주소, 업종 등) |
opendart_search_disclosure | 공시 검색 (기간, 유형, 페이지네이션) |
공시 원문 (1개)
| Tool | 설명 |
|---|
opendart_get_document | 공시 원문 조회 (접수번호 기준). 원문이 수 MB라 목차 → 섹션 순으로 나눠서 읽습니다. |
원문은 ZIP으로 내려받아 압축을 풀고, XML 태그를 제거해 읽기 좋은 텍스트로 변환합니다. 표는 A | B 형태로 표시됩니다.
| mode | 설명 |
|---|
toc (기본값) | 섹션 제목 목록과 각 섹션 분량, 첨부 문서 목록. 여기서 시작하세요. |
find | query 키워드가 어디 있는지 검색. 섹션별로 묶어 건수와 위치를 알려줍니다. |
section | 목차 번호("3") 또는 제목 키워드("사업의 내용")로 한 섹션만 조회 |
full | 원문 전체. 짧은 공시용이며, 길면 잘립니다. |
find 결과는 그대로 다음 호출이 됩니다:
"충당부채" 검색 결과: 41건 / 5개 섹션 — 범위: 전체 문서
1. #24 3. 연결재무제표 주석 — 19건
…주석 20 : 충당부채의 측정의 주요 가정…
→ mode="section", section="24", offset=3279
2. #30 5. 재무제표 주석 — 17건
...
하나의 접수번호에는 본문과 첨부 문서가 함께 들어 있습니다 (사업보고서 → 감사보고서, 연결감사보고서).
mode="toc"가 목록을 보여주며 attachment="2" 또는 attachment="감사보고서"로 골라 읽습니다.
응답은 max_chars(기본 20,000 / 최대 50,000)로 제한되며, 잘린 경우 전체 분량과 다음 offset을 함께 안내합니다.
offset으로 이어 읽으면 아무리 긴 섹션도 끝까지 읽을 수 있습니다.
주석 구조는 회사마다 다릅니다. 대기업은 주석마다 제목이 있어 section으로 바로 선택되지만,
중소형사는 주석 전체가 한 섹션에 뭉쳐 있습니다(예: 비나텍 사업보고서, 약 74,000자).
이때는 find로 위치를 찾은 뒤 그 offset부터 읽으세요.
재무 정보 (7개)
| Tool | 설명 |
|---|
opendart_single_financial_accounts | 단일회사 주요계정 (매출, 영업이익, 자산 등) |
opendart_multi_financial_accounts | 다중회사 주요계정 비교 (최대 100개) |
opendart_full_financial_statement | 전체 재무제표 (BS, IS, CF 전 항목) |
opendart_single_financial_index | 단일회사 재무지표 (수익성, 안정성, 성장성) |
opendart_multi_financial_index | 다중회사 재무지표 비교 |
opendart_xbrl_taxonomy | XBRL 표준 계정과목 분류 |
opendart_dividend_info | 배당 관련 정보 |
정기보고서 세부 항목 (24개)
| Category | Tools | 설명 |
|---|
| 주주 | 3 | 최대주주, 최대주주 변동, 소액주주 현황 |
| 임원/직원 | 3 | 임원 현황, 직원 현황, 사외이사 |
| 보수 | 5 | 개인별, 전체, 상위5인, 미등기임원, 승인총액 |
| 주식 | 3 | 발행주식총수, 증자/감자 현황, 자기주식 |
| 감사 | 3 | 감사의견, 회계감사 계약, 비감사 서비스 |
| 채무증권 | 5 | 발행실적, 기업어음, 단기사채, 회사채, 신종자본증권, 조건부자본증권 |
| 투자/자금 | 3 | 타법인 출자, 공모자금, 사모자금 사용내역 |
주주 보유 보고 (2개)
| Tool | 설명 |
|---|
opendart_major_stockholding | 대량보유 상황보고 (5% 이상) |
opendart_executive_stockholding | 임원/주요주주 보유 보고 |
주요사항보고서 (36개)
| Category | Tools | 설명 |
|---|
| 자본 변동 | 4 | 유상증자, 무상증자, 유무상증자, 감자 |
| 조직 변경 | 3 | 합병, 분할, 분할합병 |
| 영업/자산 양수도 | 7 | 영업양수, 영업양도, 유형자산 양수/양도, 타법인 주식 취득/처분, 자산양수도(풋백옵션) |
| 자기주식 | 5 | 취득, 처분, 신탁 체결, 신탁 해지, 주식교환/이전 |
| 사채 | 7 | 전환사채, 신주인수권부사채, 교환사채, 조건부자본증권, 주식관련사채 양수/양도, 주식배당 |
| 해외상장 | 4 | 상장/폐지 결정, 상장/폐지 현황 |
| 법률/경영 | 6 | 채권은행관리 개시/중단, 채무불이행, 소송, 영업정지, 회생절차, 해산 |
증권신고서 (6개)
| Tool | 설명 |
|---|
opendart_equity_securities_reg | 지분증권 신고서 |
opendart_debt_securities_reg | 채무증권 신고서 |
opendart_depositary_receipts_reg | 예탁증권 신고서 |
opendart_merger_reg | 합병 신고서 |
opendart_stock_exchange_reg | 주식교환 신고서 |
opendart_division_reg | 분할 신고서 |
Usage Examples
Claude에서 다음과 같이 사용하세요:
- "삼성전자의 20XX년 재무제표를 보여줘"
- "SK하이닉스의 최신 최대주주 현황을 알려줘"
- "카카오의 최근 공시 10개를 검색해줘"
- "현대자동차의 20XX년 임원 보수 현황을 보여줘"
- "LG에너지솔루션에 전환사채 발행 결정이 있었는지 확인해줘"
- "삼성전자 최신 사업보고서에서 '사업의 내용' 부분 원문을 읽어줘"
- "비나텍 사업보고서에서 충당부채 관련 내용을 찾아줘"
- "삼성전자 최신 사업보고서의 감사보고서에서 핵심감사사항을 보여줘"
Tech Stack
- Runtime: Next.js 16 + TypeScript
- MCP: mcp-handler + @modelcontextprotocol/sdk
- Deploy: Vercel (Streamable HTTP, Seoul region 권장)
- ZIP: fflate (corp code XML 압축 해제)
License
MIT
