MCP OpenDART

Access financial data from Korea's OpenDART (Data Analysis, Retrieval and Transfer System) for AI language models.

GitHub

한국어 | English

MCP OpenDART

License PyPI Version PyPI Downloads

OpenDART(금융감독원 전자공시시스템)를 위한 Model Context Protocol(MCP) 서버입니다. 이 통합은 데이터 프라이버시와 보안을 유지하면서 OpenDART와의 안전하고 맥락적인 AI 상호작용을 가능하게 합니다.

사용 예시

AI 어시스턴트에게 다음과 같은 요청을 할 수 있습니다:

  • 📊 재무 보고서 - "삼성전자의 최신 분기 보고서를 가져와주세요"
  • 🔍 공시 검색 - "지난달 코스피 기업들의 주요 지분 변동을 찾아주세요"
  • 📈 기업 분석 - "현대자동차의 지난 3년간의 재무제표를 보여주세요"
  • ⚡ 실시간 업데이트 - "오늘의 기술 섹터 중요 공시를 가져와주세요"

기능 데모

[데모 영상이 추가될 예정입니다]

지원 기능

기능지원 상태설명
공시정보✅ 완전 지원기업 정보, 공시 문서 조회
정기보고서 주요정보✅ 완전 지원사업보고서, 분기/반기보고서 주요 정보
정기보고서 재무정보✅ 완전 지원재무제표, XBRL 데이터
지분공시 종합정보✅ 완전 지원주요 주주 및 임원 지분 현황
주요사항보고서 주요정보✅ 완전 지원주요사항보고서 핵심 정보
증권신고서 주요정보✅ 완전 지원증권발행 신고 주요 정보
재무제표 주석 자동 추출✅ 완전 지원연결재무제표 주석, 재무제표 주석 자동 추출 및 캐싱
사업의 내용 파싱✅ 완전 지원II. 사업의 내용 섹션 동적 파싱 및 구조화
회사의 개요 파싱✅ 완전 지원I. 회사의 개요 섹션 동적 파싱 및 구조화
구조화된 데이터 검색✅ 완전 지원테이블 및 문단 단위 의미 기반 검색
지능적 XML 파일 선택✅ 완전 지원ZIP 파일에서 최적의 비즈니스 보고서 자동 선택

빠른 시작 가이드

1. 인증 설정

먼저 OpenDART API 키를 얻으세요:

  1. OpenDART에 접속
  2. 회원가입 후 API 키 신청

2. 설치

# 저장소 복제
git clone https://github.com/ChangooLee/mcp-opendart.git
cd mcp-opendart

# [중요] Python 3.10 이상 사용 필수. 아래 'Python 3.10+ 설치 안내' 참고

# 가상 환경 생성
python3.10 -m venv .venv
source .venv/bin/activate

# 패키지 설치
# python 3.10 이상이 필요 
python3 -m pip install --upgrade pip
uv pip install -e .

Python 3.10+ 설치 안내

Python 버전 확인 (3.10 이상 필요)

python3 --version

만약 Python 버전이 3.10 미만이라면, 아래 안내에 따라 Python 3.10 이상을 설치하세요:

macOS

  • 공식 웹사이트에서 최신 Python 설치 파일을 다운로드: https://www.python.org/downloads/macos/
  • 또는 Homebrew를 사용하는 경우: 
    brew install python@3.10
    설치 후 python3.10 명령어를 사용해야 할 수 있습니다.

Windows

  • 공식 웹사이트에서 최신 Python 설치 파일을 다운로드 및 실행: https://www.python.org/downloads/windows/
  • 설치 시 "Add Python to PATH" 옵션을 반드시 체크하세요.
  • 설치 후 터미널을 재시작하고 python 또는 python3 명령어를 사용하세요.

Linux (Ubuntu/Debian)

  • 패키지 목록을 업데이트하고 Python 3.10 설치: 
    sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-distutils
  • python3.10 명령어를 사용해야 할 수 있습니다.

Linux (Fedora/CentOS/RHEL)

  • Python 3.10 설치: 
    sudo dnf install python3.10

IDE 통합

MCP OpenDART는 IDE 통합을 통해 AI 어시스턴트와 함께 사용하도록 설계되었습니다.

Claude Desktop 설정 방법

  1. 햄버거 메뉴(☰) > Settings > Developer > "Edit Config" 버튼 클릭
  2. 아래 설정을 추가:
{
  "mcpServers": {
    "mcp-opendart": {
      "command": "YOUR_LOCATION/.venv/bin/mcp-opendart",
      "env": {
        "OPENDART_API_KEY": "API-KEY",
        "OPENDART_BASE_URL": "https://opendart.fss.or.kr/api/",
        "HOST": "0.0.0.0",
        "PORT": "8000",
        "TRANSPORT": "stdio",
        "LOG_LEVEL": "INFO",
        "MCP_SERVER_NAME": "mcp-opendart"
      }
    }
  }
}

Streamable HTTP 설정 (선택 사항)

HTTP transport를 사용하여 streamable-http로 실행할 수도 있습니다:

{
  "mcpServers": {
    "mcp-opendart": {
      "command": "YOUR_LOCATION/.venv/bin/mcp-opendart",
      "env": {
        "OPENDART_API_KEY": "API-KEY",
        "OPENDART_BASE_URL": "https://opendart.fss.or.kr/api/",
        "HOST": "0.0.0.0",
        "PORT": "9000",
        "TRANSPORT": "http",
        "LOG_LEVEL": "INFO",
        "MCP_SERVER_NAME": "mcp-opendart"
      }
    }
  }
}

[!NOTE]

  • TRANSPORT="http" 설정시 서버는 streamable-http 방식으로 실행됩니다
  • 엔드포인트: http://HOST:PORT/mcp

[!NOTE]

  • YOUR_LOCATION: 가상환경이 설치된 실제 경로로 변경
  • API-KEY: 발급받은 OpenDART API 키로 변경

주요 환경 변수

  • OPENDART_API_KEY: OpenDART API 키
  • OPENDART_BASE_URL: API 기본 URL (기본값: 공식 URL)
  • HOST: 서버 호스트 (기본값: 0.0.0.0)
  • PORT: 서버 포트 (기본값: 8000)
  • TRANSPORT: 전송 방식 (stdio 권장, http로 설정시 streamable-http 지원)
  • LOG_LEVEL: 로깅 레벨 (INFO, DEBUG 등)
  • MCP_SERVER_NAME: 서버 이름

재무제표 주석 자동 추출 및 검색 시스템

시스템 아키텍처

graph TD
    A[공시서류 다운로드] --> B[XML 파싱]
    B --> C{재무제표 주석 존재?}
    C -->|Yes| D[재무제표 주석 추출]
    C -->|No| E[다른 보고서 검색 안내]
    E --> F[LLM이 다른 보고서 선택]
    F --> A
    D --> G[섹션별 분류]
    G --> H[연결재무제표 주석]
    G --> I[재무제표 주석]
    H --> J[테이블 추출]
    H --> K[문단 추출]
    I --> L[테이블 추출]
    I --> M[문단 추출]
    J --> N[구조화된 JSON 저장]
    K --> N
    L --> N
    M --> N
    N --> O[disclosure_cache 저장]
    O --> P[검색 가능한 상태]
    P --> Q[키워드 검색]
    Q --> R[테이블 검색 결과]
    Q --> S[문단 검색 결과]

캐싱 구조

disclosure_cache/
├── financial_notes_{rcp_no}/
│   ├── metadata.json
│   ├── disclosure_{rcp_no}.json
│   ├── consolidated_notes/          # 3. 연결재무제표 주석
│   │   ├── metadata.json
│   │   ├── tables/
│   │   └── paragraphs/
│   ├── separate_notes/              # 5. 재무제표 주석
│   │   ├── metadata.json
│   │   ├── tables/
│   │   └── paragraphs/
│   ├── business_content/            # II. 사업의 내용
│   │   ├── metadata.json
│   │   └── subsections/
│   │       ├── 1_사업의_개요/
│   │       ├── 2_영업의_현황/
│   │       ├── 3_파생상품거래_현황/
│   │       ├── 4_영업설비/
│   │       └── 5_재무건전성_등_기타_참고사항/
│   └── company_overview/            # I. 회사의 개요
│       ├── metadata.json
│       └── subsections/
│           ├── 1_회사의_개요/
│           ├── 2_회사의_연혁/
│           ├── 3_자본금_변동사항/
│           ├── 4_주식의_총수_등/
│           └── 5_정관에_관한_사항/

검색 기능

  • 테이블 검색: 헤더와 데이터 셀에서 키워드 검색
  • 문단 검색: 재무제표 주석 문단에서 키워드 검색
  • 섹션별 검색: 연결재무제표 주석, 재무제표 주석, 사업의 내용, 회사의 개요 검색
  • 컨텍스트 분류: 기본정보, 사업정보, 재무정보로 자동 분류
  • 자동 확장: 사업의 내용, 회사의 개요 검색 시 모든 하위 섹션 자동 포함
  • 대소문자 구분: 선택적 대소문자 구분 검색

도구

OpenDART 도구

  • ds001_disclosure: 공시정보 검색 및 조회
  • ds002_periodic: 정기보고서 주요정보 조회
  • ds003_financial: 정기보고서 재무정보 조회
  • ds004_ownership: 지분공시 종합정보 조회
  • ds005_major: 주요사항보고서 주요정보 조회
  • ds006_securities: 증권신고서 주요정보 조회
카테고리도구
공시정보get_corporation_code_by_name, get_disclosure_list, get_corporation_info, get_disclosure_document, get_corporation_code
정기보고서 주요정보get_annual_report, get_quarterly_report, get_semi_annual_report
정기보고서 재무정보get_single_acnt, get_multi_acnt, get_xbrl_file, get_single_acc, get_xbrl_taxonomy, get_single_index, get_multi_index
지분공시 종합정보get_major_shareholders, get_executive_holdings
주요사항보고서 주요정보get_major_reports, get_business_reports
증권신고서 주요정보get_securities_filing, get_prospectus
재무제표 주석 검색search_financial_notes
공시 문서 다운로드get_disclosure_document

문제 해결 및 디버깅

일반적인 문제

  • 인증 실패:

    • API 키가 유효하고 활성 상태인지 확인
    • API 키에 필요한 권한이 있는지 확인
    • API 호출 한도(일 20,000회) 초과 여부 확인

  • 데이터 접근 문제:

    • 일부 데이터는 추가 권한이 필요할 수 있음
    • 특정 데이터는 지연된 접근(최대 24시간)이 있을 수 있음
    • 회사가 접근 가능한 범위 내에 있는지 확인

  • 연결 문제:

    • 인터넷 연결 확인
    • OpenDART API 서비스 가용성 확인
    • 방화벽이 연결을 차단하지 않는지 확인

디버깅 도구

# 상세 로깅 활성화
export LOG_LEVEL=DEBUG

# 로그 확인
tail -f opendart.log

# API 연결 테스트
python -m mcp_opendart test-connection

보안

  • API 키를 절대 공유하지 마세요
  • .env 파일을 안전하게 보관하세요
  • 적절한 속도 제한을 사용하세요
  • API 사용량을 모니터링하세요
  • 민감한 데이터는 환경 변수에 저장하세요

기여하기

기여를 환영합니다! 기여하시려면:

  1. 저장소를 포크하세요
  2. 기능 브랜치를 만드세요
  3. 변경사항을 작성하세요
  4. 풀 리퀘스트를 제출하세요

라이선스

이 프로젝트는 비상업적, 개인적, 연구, 학습, 비영리 목적에 한해 사용할 수 있습니다. 상업적 사용, 재배포, 2차 저작물의 상업적 이용은 엄격히 금지됩니다. 자세한 내용은 LICENSE 파일을 참고하세요.

이 프로젝트는 공식 OpenDART 제품이 아닙니다. OpenDART는 금융감독원의 등록 상표입니다.

Related Servers