opendart-mcp-server

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 스킬 동작 방식

• 회사명·사업연도·기간·범위(연결/별도)를 파악하고, 모호하면 반드시 사용자에게 확인합니다.
• get_corp_codes와 search_disclosures로 해당 기간 정기보고서의 rcept_no 1건을 찾습니다.
• list_financial_document_candidates가 공시 계열 전체의 ZIP XML을 먼저 검사하고, 빠진 첨부만 DART 내부 문서 목록으로 보완합니다. AI가 요청 기간·연결/별도에 맞는 candidate_id를 고릅니다.
• create_financial_workbook이 선택 문서만 받아 재무제표·주석을 파싱하고 Excel을 생성·검증합니다.
• 감사·검토보고서 첨부가 실제로 없으면 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 --upgrade --from opendart-mcp-server opendartmcp로 최신 PyPI 배포본을 실행합니다. 현재 버전은 1.4.12입니다.

제공 도구

워크플로 도구 (2)

Tool	Description
list_financial_document_candidates	접수번호 1건으로 공시 계열 전체의 첨부·본문 제목 목록 반환 (원문 미반환)
create_financial_workbook	선택한 문서에서 검증된 재무제표 Excel 생성 (원문은 반환하지 않고 파일 경로만 반환)

OpenDART API 도구 (85개)

DS001 · 공시정보 (4)

목록 펼치기

Tool	Description
search_disclosures	공시 목록 검색
get_company_info	기업 기본정보 조회
get_disclosure_document	공시 원문 문서 조회
get_corp_codes	회사명/종목코드로 법인 고유번호(corp_code) 검색

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

목록 펼치기

Tool	Description
get_capital_change_status	증자(감자) 현황
get_dividend_info	배당에 관한 사항
get_treasury_stock	자기주식 취득 및 처분 현황
get_largest_shareholder	최대주주 현황
get_largest_shareholder_changes	최대주주 변동현황
get_minority_shareholders	소액주주 현황
get_executives	임원 현황
get_employees	직원 현황
get_executive_compensation_total	이사·감사 전체의 보수현황
get_executive_compensation_gmtsck	이사·감사 전체 보수현황 (주총승인금액)
get_executive_compensation_type	이사·감사 전체 보수현황 (유형별)
get_executive_compensation_individual	이사·감사 개인별 보수현황 5억원 이상
get_individual_pay_over5	개인별 보수지급 금액 5억 이상 상위 5인
get_executive_compensation_individual_v2	이사·감사 개인별 보수현황 5억원 이상 (V2)
get_individual_pay_over5_v2	개인별 보수지급 금액 상위 5인 (V2)
get_unregistered_executives	미등기임원 보수현황
get_investment_in_other_corps	타법인 출자현황
get_audit_opinion	회계감사인 명칭 및 감사의견
get_audit_fee	감사용역체결현황
get_non_audit_service	비감사용역 계약체결 현황
get_outside_director_changes	사외이사 및 변동현황
get_stock_total_qty	주식의 총수 현황
get_bond_issuance	채무증권 발행실적
get_commercial_paper	기업어음증권 미상환 잔액
get_short_term_bond	단기사채 미상환 잔액
get_corp_bond_outstanding	회사채 미상환 잔액
get_hybrid_bond	신종자본증권 미상환 잔액
get_debt_securities_outstanding	조건부자본증권 미상환 잔액
get_public_offering_fund_usage	공모자금 사용내역
get_private_placement_fund_usage	사모자금 사용내역

DS003 · 재무정보 (7)

목록 펼치기

Tool	Description
get_single_company_account	단일 회사 주요 재무제표 계정 조회
get_multi_company_account	다중 회사 주요 재무제표 계정 조회
get_xbrl_financial	XBRL 재무제표 원본 조회
get_single_full_financial	단일 회사 전체 재무제표 조회
get_xbrl_taxonomy	XBRL 표준 재무제표 양식 조회
get_single_financial_index	단일 회사 주요 재무지표 조회
get_multi_financial_index	다중 회사 주요 재무지표 조회

DS004 · 지분공시 (2)

목록 펼치기

Tool	Description
get_large_holding_report	5% 이상 대량보유 현황
get_executive_stock_report	임원 및 주요주주 소유보고

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

목록 펼치기

Tool	Description
get_paid_capital_increase	유상증자 결정
get_free_capital_increase	무상증자 결정
get_paid_free_capital_increase	유무상증자 결정
get_capital_reduction	감자 결정
get_convertible_bond	전환사채권 발행결정
get_bond_with_warrants	신주인수권부사채권 발행결정
get_exchangeable_bond	교환사채권 발행결정
get_conditional_capital_issuance	상각형 조건부자본증권 발행결정
get_stock_acquisition	자기주식 취득 결정
get_stock_disposal	자기주식 처분 결정
get_treasury_stock_trust_conclude	자기주식취득 신탁계약 체결 결정
get_treasury_stock_trust_terminate	자기주식취득 신탁계약 해지 결정
get_merger_decision	회사합병 결정
get_division_decision	회사분할 결정
get_division_merger_decision	회사분할합병 결정
get_stock_exchange_decision	주식교환·이전 결정
get_business_acquisition	영업양수 결정
get_business_transfer	영업양도 결정
get_tangible_asset_acquisition	유형자산 양수 결정
get_tangible_asset_transfer	유형자산 양도 결정
get_equity_investment_acquisition	타법인 주식 및 출자증권 양수결정
get_equity_investment_transfer	타법인 주식 및 출자증권 양도결정
get_equity_securities_acquisition	주권 관련 사채권 양수 결정
get_equity_securities_transfer	주권 관련 사채권 양도 결정
get_other_asset_acquisition	자산양수도(기타), 풋백옵션
get_overseas_listing_decision	해외 증권시장 상장 결정
get_overseas_delisting_decision	해외 증권시장 상장폐지 결정
get_overseas_listing	해외 증권시장 상장
get_overseas_delisting	해외 증권시장 상장폐지
get_bankruptcy_report	부도발생
get_business_suspension_report	영업정지
get_rehabilitation_report	회생절차 개시신청
get_dissolution_report	해산사유 발생
get_creditor_management	채권은행 등의 관리절차 개시
get_creditor_management_suspension	채권은행 등의 관리절차 중단
get_lawsuit_report	소송 등의 제기

DS006 · 증권신고서 (6)

목록 펼치기

Tool	Description
get_equity_securities	지분증권 증권신고서
get_debt_securities	채무증권(회사채) 증권신고서
get_depositary_receipts	증권예탁증권(DR) 증권신고서
get_merger_securities	합병 관련 증권신고서
get_stock_exchange_securities	주식 포괄적 교환·이전 증권신고서
get_division_securities	분할 관련 증권신고서

주의사항

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