한국어 | English

MCP OpenDART

Name: MCP OpenDART
Author: ChangooLee

License PyPI Version PyPI Downloads

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

사용 예시

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

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

기능 데모

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

지원 기능

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

빠른 시작 가이드

1. 인증 설정

먼저 OpenDART API 키를 얻으세요:

OpenDART에 접속
회원가입 후 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 .

Docker로 실행하기

Docker 이미지 로드 (사전 빌드된 이미지 사용)

저장소에 포함된 사전 빌드된 이미지를 사용할 수 있습니다:

# Git LFS가 설치되어 있다면 자동으로 다운로드됩니다 # Git LFS 설치: https://git-lfs.github.com/ git lfs pull # 이미지 로드 docker load -i mcp-opendart-image.tar.gz

Docker 이미지 빌드

직접 빌드하려면:

# Docker 이미지 빌드 docker build -t mcp-opendart:latest .

Docker 컨테이너 실행

방법 1: 환경변수 직접 전달 (-e 옵션)

# 기본 실행 (포트 8000) docker run -d \ --name mcp-opendart \ -p 8000:8000 \ -e OPENDART_API_KEY=your-api-key-here \ -e TRANSPORT=http \ -e HOST=0.0.0.0 \ -e PORT=8000 \ -e LOG_LEVEL=INFO \ mcp-opendart:latest # 다른 포트로 실행 (예: 9000) docker run -d \ --name mcp-opendart \ -p 9000:9000 \ -e OPENDART_API_KEY=your-api-key-here \ -e TRANSPORT=http \ -e HOST=0.0.0.0 \ -e PORT=9000 \ -e LOG_LEVEL=INFO \ mcp-opendart:latest

방법 2: .env 파일 사용 (권장)

.env 파일을 생성하고 환경변수를 설정한 후 사용:

# .env 파일 예시 # OPENDART_API_KEY=your-api-key-here # TRANSPORT=http # HOST=0.0.0.0 # PORT=8000 # LOG_LEVEL=INFO # MCP_SERVER_NAME=opendart-mcp # .env 파일을 사용하여 실행 docker run -d \ --name mcp-opendart \ -p 8000:8000 \ --env-file .env \ mcp-opendart:latest

참고: .env 파일을 사용하면 API 키 등 민감한 정보를 코드에 노출하지 않고 관리할 수 있습니다.

Docker Compose 사용 (선택사항)

docker-compose.yml 파일을 생성하여 사용할 수 있습니다:

version: '3.8' services: mcp-opendart: build: . container_name: mcp-opendart ports: - "8000:8000" environment: - OPENDART_API_KEY=${OPENDART_API_KEY} - TRANSPORT=http - HOST=0.0.0.0 - PORT=8000 - LOG_LEVEL=INFO restart: unless-stopped

실행:

docker-compose up -d

접속 확인

서버가 정상적으로 실행되면 다음 엔드포인트로 접속할 수 있습니다:

MCP 엔드포인트: http://localhost:8000/mcp
헬스체크: Docker의 내장 헬스체크 사용

로그 확인

# 컨테이너 로그 확인 docker logs mcp-opendart # 실시간 로그 확인 docker logs -f mcp-opendart

컨테이너 중지 및 제거

# 컨테이너 중지 docker stop mcp-opendart # 컨테이너 제거 docker rm mcp-opendart # 이미지 제거 docker rmi mcp-opendart:latest

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 설정 방법

햄버거 메뉴(☰) > Settings > Developer > "Edit Config" 버튼 클릭
아래 설정을 추가:

{ "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 사용량을 모니터링하세요
민감한 데이터는 환경 변수에 저장하세요

기여하기

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

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

라이선스

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

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