OpenDART Plugin

OpenDART API(금융감독원 전자공시시스템 오픈API)를 이용해 MCP 서버를 만들고, 특정 기업의 재무제표를 Excel 파일로 만들어주는 SKILL을 포함한 Claude Code / Codex 플러그인입니다.

• "하이닉스 2025년 연결재무제표 엑셀로 만들어줘" 한마디로 재무제표 원문(감사보고서)을 가져와 시트별로 정리하고, 각 주석번호에 하이퍼링크까지 걸린 .xlsx 파일을 생성합니다.
• 공시 검색, 재무제표, 임원/주주 현황, 주요사항보고서 등 DS001~DS006 전 영역 85개 API 도구와 Excel 워크플로 도구를 자연어 질의로 사용할 수 있습니다.

데모 영상

https://github.com/user-attachments/assets/6b5664fd-73cb-409c-adec-e23df6ed1198

준비물

• Claude Code 또는 Codex CLI
• Python 3.11+
• uv / uvx (설치) — 없다면 pip install uv
• OpenDART API KEY: OpenDART에서 KEY 발급

설치

플러그인을 설치하면 open-dart MCP 서버 설정과 opendart-excel 스킬이 함께 설치됩니다.

Claude Code

/plugin marketplace add gyeongmin100/Open-Dart-Plugin
/plugin install opendart@open-dart-plugin

설치 중 DART_API_KEY를 입력하라는 프롬프트가 뜹니다.

사용 예:

/opendart:opendart-excel 삼성전자 2023년 연결 재무제표를 엑셀로 만들어줘

Codex

codex plugin marketplace add gyeongmin100/Open-Dart-Plugin

Codex에서 /plugins를 열고 OpenDART MCP marketplace의 opendart 플러그인을 설치합니다. Codex 실행 환경에는 DART_API_KEY가 미리 설정되어 있어야 합니다.

export DART_API_KEY="your-api-key"      # bash/zsh
$env:DART_API_KEY="your-api-key"        # PowerShell

사용 예:

$opendart 삼성전자 2023년 연결 재무제표를 엑셀로 만들어줘

AI 에이전트용 설치 프롬프트

아래 블록을 그대로 복사해서 Claude Code나 Codex 채팅창에 붙여넣으면, 에이전트가 알아서 marketplace 등록 → 플러그인 설치 → API 키 설정까지 진행합니다.

OpenDART 플러그인을 설치해줘.

1. 저장소: https://github.com/gyeongmin100/Open-Dart-Plugin
2. Claude Code라면:
   - /plugin marketplace add gyeongmin100/Open-Dart-Plugin 실행
   - /plugin install opendart@open-dart-plugin 실행
   - 설치 중 DART_API_KEY를 물어보면, 아직 없다고 하면 https://opendart.fss.or.kr 에서
     API 키를 발급받는 방법을 안내해줘.
   Codex라면:
   - codex plugin marketplace add gyeongmin100/Open-Dart-Plugin 실행
   - /plugins 메뉴에서 "OpenDART MCP" marketplace의 opendart 플러그인 설치 안내
   - 실행 환경에 DART_API_KEY 환경변수가 필요하다는 것도 안내해줘.
3. 설치가 끝나면 opendart-excel 스킬로 "삼성전자 2023년 연결재무제표 엑셀로 만들어줘" 같은
   요청을 처리할 수 있다는 것을 확인해줘.
4. Python 3.11+ 와 uv/uvx가 없으면 먼저 설치 방법을 안내해줘 (pip install uv).

사용 예시

삼성전자 최근 공시 보여줘
카카오 2023년 재무제표 알려줘
현대자동차 최대주주 현황은?
LG전자 임원 현황 조회해줘
SK하이닉스 배당 이력 알려줘
2024년 합병 공시 목록 검색해줘
삼성전자 2023년 연결 재무제표를 엑셀로 만들어줘   ← opendart 플러그인

opendart-excel 스킬 동작 방식

1. 회사명·사업연도·기간·범위(연결/별도)를 파악하고, 모호하면 반드시 사용자에게 확인합니다.
2. get_corp_codes와 search_disclosures로 해당 기간 정기보고서의 rcept_no 1건을 찾습니다.
3. list_financial_document_candidates가 공시 계열 전체의 ZIP XML을 먼저 검사하고, 빠진 첨부만 DART 내부 문서 목록으로 보완합니다. AI가 요청 기간·연결/별도에 맞는 candidate_id를 고릅니다.
4. create_financial_workbook이 선택 문서만 받아 재무제표·주석을 파싱하고 Excel을 생성·검증합니다.
5. 감사·검토보고서 첨부가 실제로 없으면 confirmation_required를 반환합니다. 사용자 승인 후 allow_body=true로 다시 호출할 때만 (본문) 후보를 쓰고 생성합니다.

정정 공시는 본문만 재제출하고 첨부는 원본 공시에 남습니다. 서버가 원본·정정·첨부정정·첨부추가 제출본의 ZIP을 모두 검사하므로 접수번호 1건이면 원본에 붙은 감사보고서까지 후보에 나옵니다. 후보의 rcept_no가 조회에 쓴 번호와 달라도 정상입니다.

공시 원문(XML/HTML)은 서버 메모리에서만 처리되어 AI에게 전달되지 않으며, 중간 파일도 남지 않습니다.

안전성:

• allow_body=true 없이는 본문 후보를 반환하거나 생성하지 않습니다. 승인 후에도 ZIP 첫 파일이 아니라 사업보고서·반기보고서·분기보고서 제목의 본문을 선택합니다.
• OpenDART HTTP 오류에는 상태 코드와 API 경로만 포함하며, httpx 로그의 crtfc_key는 ***로 가립니다.
• 검증 실패·취소·최종 파일 이동 실패 시 서버가 만든 임시 파일과 빈 선점 파일을 정리합니다.

프로젝트 구조

Open-Dart-Plugin/
├── src/opendartmcp/              # MCP 서버 본체 (PyPI: opendart-mcp-server)
│   ├── server.py                  # MCP 서버 엔트리포인트 + CLI (config set-api-key 등)
│   ├── client.py                  # DartClient — OpenDART Open API 호출 래퍼
│   ├── config.py                  # API 키 저장/조회 (CLI 등록 vs 환경변수)
│   ├── errors.py                  # 안전한 DART API/HTTP 예외
│   ├── excel/                     # 재무제표 Excel 생성 (서버가 직접 수행)
│   │   ├── candidates.py          # ZIP + DART 화면 첨부 후보 조회/로딩
│   │   ├── dartdoc.py             # DART 원문 XML/HTML 파서
│   │   ├── build_financial_excel.py # 모델 → Excel 워크북 생성
│   │   ├── verify_workbook.py     # 생성된 Excel 자동 검증
│   │   └── workflow.py            # ZIP 1회 다운로드 → 문서 선택 → 파싱 → 생성 → 검증
│   └── tools/                     # MCP 도구 정의 — DS001~DS006 그룹별 파일
│       ├── disclosure.py          # DS001 공시정보 (검색/기업정보/원문/고유번호검색)
│       ├── business_report.py     # DS002 정기보고서 주요정보
│       ├── financial.py           # DS003 재무정보
│       ├── stock_holdings.py      # DS004 지분공시
│       ├── major_report.py        # DS005 주요사항보고서
│       ├── securities.py          # DS006 증권신고서
│       └── workbook.py            # 후보 조회 + Excel 생성 워크플로 도구
│
├── plugins/                       # Claude Code / Codex 플러그인 소스
│   └── {claude,codex}/opendart/   # 각 클라이언트용 플러그인 (공통 구성)
│       ├── .{claude,codex}-plugin/plugin.json # 플러그인 manifest
│       ├── .mcp.json              # 플러그인이 MCP 서버를 실행하는 설정
│       └── skills/opendart-excel/
│           └── SKILL.md           # 엑셀 생성 스킬 지침서 (에이전트가 읽고 따름)
│
├── .claude-plugin/marketplace.json    # Claude Code 마켓플레이스 정의
├── .agents/plugins/marketplace.json   # Codex 마켓플레이스 정의
├── .github/workflows/publish.yml      # GitHub Release 생성 시 PyPI 자동 배포
├── pyproject.toml                     # opendart-mcp-server 패키지 빌드 설정
└── sample.png                         # README 예시 이미지

변경사항: 재무제표 Excel 생성 코드는 플러그인의 skills/opendart-excel/scripts/(Claude·Codex 두 벌)에서 src/opendartmcp/excel/ 한 벌로 옮겨졌고, MCP 서버가 직접 실행합니다. 플러그인 쪽 스크립트와 requirements.txt, 의존성 자동 설치 헬퍼는 제거되었습니다. 기존 85개 OpenDART API 도구는 그대로 유지됩니다.

플러그인의 .mcp.json은 uvx --from opendart-mcp-server opendartmcp로 PyPI 배포본을 실행합니다. 현재 버전은 1.4.7입니다.

제공 도구

워크플로 도구 (2)

OpenDART API 도구 (85개)

DS001 · 공시정보 (4)

DS002 · 정기보고서 주요정보 (30)

DS003 · 재무정보 (7)

DS004 · 지분공시 (2)

DS005 · 주요사항보고서 (36)

DS006 · 증권신고서 (6)

주의사항

• API 일일 호출 한도: 10,000건 (초과 시 오류 발생)
• opendart-excel 스킬은 검증에 실패한 Excel 파일은 전달하지 않습니다.