MCP OpenDART

한국어 | [English](README_en.md) # MCP OpenDART    OpenDART(금융감독원 전자공시시스템)를 위한 Model Context Protocol(MCP) 서버입니다. 이 통합은 데이터 프라이버시와 보안을 유지하면서 OpenDART와의 안전하고 맥락적인 AI 상호작용을 가능하게 합니다. ## 사용 예시 AI 어시스턴트에게 다음과 같은 요청을 할 수 있습니다: - **📊 재무 보고서** - "삼성전자의 최신 분기 보고서를 가져와주세요" - **🔍 공시 검색** - "지난달 코스피 기업들의 주요 지분 변동을 찾아주세요" - **📈 기업 분석** - "현대자동차의 지난 3년간의 재무제표를 보여주세요" - **⚡ 실시간 업데이트** - "오늘의 기술 섹터 중요 공시를 가져와주세요" ### 기능 데모 [데모 영상이 추가될 예정입니다] ### 지원 기능 | 기능 | 지원 상태 | 설명 | |---------|---------------|-------------| | **공시정보** | ✅ 완전 지원 | 기업 정보, 공시 문서 조회 | | **정기보고서 주요정보** | ✅ 완전 지원 | 사업보고서, 분기/반기보고서 주요 정보 | | **정기보고서 재무정보** | ✅ 완전 지원 | 재무제표, XBRL 데이터 | | **지분공시 종합정보** | ✅ 완전 지원 | 주요 주주 및 임원 지분 현황 | | **주요사항보고서 주요정보** | ✅ 완전 지원 | 주요사항보고서 핵심 정보 | | **증권신고서 주요정보** | ✅ 완전 지원 | 증권발행 신고 주요 정보 | | **재무제표 주석 자동 추출** | ✅ 완전 지원 | 연결재무제표 주석, 재무제표 주석 자동 추출 및 캐싱 | | **사업의 내용 파싱** | ✅ 완전 지원 | II. 사업의 내용 섹션 동적 파싱 및 구조화 | | **회사의 개요 파싱** | ✅ 완전 지원 | I. 회사의 개요 섹션 동적 파싱 및 구조화 | | **구조화된 데이터 검색** | ✅ 완전 지원 | 테이블 및 문단 단위 의미 기반 검색 | | **지능적 XML 파일 선택** | ✅ 완전 지원 | ZIP 파일에서 최적의 비즈니스 보고서 자동 선택 | ## 빠른 시작 가이드 ### 1. 인증 설정 먼저 OpenDART API 키를 얻으세요: 1. [OpenDART](https://opendart.fss.or.kr/)에 접속 2. 회원가입 후 API 키 신청 ### 2. 설치 ```bash # 저장소 복제 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 이미지 로드 (사전 빌드된 이미지 사용) 저장소에 포함된 사전 빌드된 이미지를 사용할 수 있습니다: ```bash # Git LFS가 설치되어 있다면 자동으로 다운로드됩니다 # Git LFS 설치: https://git-lfs.github.com/ git lfs pull # 이미지 로드 docker load -i mcp-opendart-image.tar.gz ``` ### Docker 이미지 빌드 직접 빌드하려면: ```bash # Docker 이미지 빌드 docker build -t mcp-opendart:latest . ``` ### Docker 컨테이너 실행 #### 방법 1: 환경변수 직접 전달 (-e 옵션) ```bash # 기본 실행 (포트 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` 파일을 생성하고 환경변수를 설정한 후 사용: ```bash # .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` 파일을 생성하여 사용할 수 있습니다: ```yaml 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 ``` 실행: ```bash docker-compose up -d ``` ### 접속 확인 서버가 정상적으로 실행되면 다음 엔드포인트로 접속할 수 있습니다: - MCP 엔드포인트: `http://localhost:8000/mcp` - 헬스체크: Docker의 내장 헬스체크 사용 ### 로그 확인 ```bash # 컨테이너 로그 확인 docker logs mcp-opendart # 실시간 로그 확인 docker logs -f mcp-opendart ``` ### 컨테이너 중지 및 제거 ```bash # 컨테이너 중지 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를 사용하는 경우: ```sh 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 설치: ```sh sudo apt update sudo apt install python3.10 python3.10-venv python3.10-distutils ``` - `python3.10` 명령어를 사용해야 할 수 있습니다. ### Linux (Fedora/CentOS/RHEL) - Python 3.10 설치: ```sh sudo dnf install python3.10 ``` ## IDE 통합 MCP OpenDART는 IDE 통합을 통해 AI 어시스턴트와 함께 사용하도록 설계되었습니다. ### Claude Desktop 설정 방법 1. 햄버거 메뉴(☰) > Settings > Developer > "Edit Config" 버튼 클릭 2. 아래 설정을 추가: ```json { "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로 실행할 수도 있습니다: ```json { "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`: 서버 이름 ## 재무제표 주석 자동 추출 및 검색 시스템 ### 시스템 아키텍처 ```mermaid 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`: 증권신고서 주요정보 조회 <details> <summary>주요 도구 목록</summary> | 카테고리 | 도구 | |----------|-------| | **공시정보** | `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` | </details> ## 문제 해결 및 디버깅 ### 일반적인 문제 - **인증 실패**: - API 키가 유효하고 활성 상태인지 확인 - API 키에 필요한 권한이 있는지 확인 - API 호출 한도(일 20,000회) 초과 여부 확인 - **데이터 접근 문제**: - 일부 데이터는 추가 권한이 필요할 수 있음 - 특정 데이터는 지연된 접근(최대 24시간)이 있을 수 있음 - 회사가 접근 가능한 범위 내에 있는지 확인 - **연결 문제**: - 인터넷 연결 확인 - OpenDART API 서비스 가용성 확인 - 방화벽이 연결을 차단하지 않는지 확인 ### 디버깅 도구 ```bash # 상세 로깅 활성화 export LOG_LEVEL=DEBUG # 로그 확인 tail -f opendart.log # API 연결 테스트 python -m mcp_opendart test-connection ``` ## 보안 - API 키를 절대 공유하지 마세요 - `.env` 파일을 안전하게 보관하세요 - 적절한 속도 제한을 사용하세요 - API 사용량을 모니터링하세요 - 민감한 데이터는 환경 변수에 저장하세요 ## 기여하기 기여를 환영합니다! 기여하시려면: 1. 저장소를 포크하세요 2. 기능 브랜치를 만드세요 3. 변경사항을 작성하세요 4. 풀 리퀘스트를 제출하세요 ## 라이선스 이 프로젝트는 비상업적, 개인적, 연구, 학습, 비영리 목적에 한해 사용할 수 있습니다. 상업적 사용, 재배포, 2차 저작물의 상업적 이용은 엄격히 금지됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요. 이 프로젝트는 공식 OpenDART 제품이 아닙니다. OpenDART는 금융감독원의 등록 상표입니다.