金融数据集成服务

韩语 | 英语

MCP OpenDART

这是为OpenDART（金融监督院电子公示系统）设计的Model Context Protocol（MCP）服务器。此集成在保持数据隐私和安全的同时，实现了与OpenDART之间安全且上下文相关的AI交互。

使用示例

您可以向AI助手提出以下请求：

• 📊 财务报告 -“请给我带来三星电子最新的季度报告。”
• 🔍 公告搜索 -“请找出上个月KOSPI（韩国综合股价指数）企业的主要股份变动”
• 📈 企业分析 -“请给我看一下现代汽车过去三年的财务报表”
• ⚡ 实时更新 -“请给我带来今天科技领域的重要公告”

功能演示

[将添加演示视频]

支持功能

快速入门指南

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 的版本”

如果Python版本低于3.10，请按照以下指南安装Python 3.10或更高版本：

macOS（发音：/ˈmækɒs/ 或 /ˈmækəs/）

• 从官方网站下载最新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. 汉堡菜单(☰) > 设置 > 开发者 > 点击“编辑配置”按钮
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"
      }
    }
  }
}

[!NOTE]（注：此标记通常用于提醒或注意事项，具体翻译可能根据上下文调整，但在此直接保留原样以体现其特殊性）

• YOUR_LOCATION更改到已安装虚拟环境的实际路径
• API-KEY使用已发放的OpenDART API密钥进行更改

主要环境变量

• OPENDART_API_KEYOpenDART API密钥
• OPENDART_BASE_URLAPI 基本 URL（默认值：官方 URL）
• HOST服务器主机（默认值：0.0.0.0）
• PORT服务器端口（默认值：8000）
• TRANSPORT传输方式（推荐使用stdio）
• 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查询证券申报书主要信息

问题解决与调试

常见问题

• 认证失败:

  • 确认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. 请 Fork 该仓库
2. 创建功能分支
3. 请编写变更内容
4. 提交完整请求

许可证

本项目仅限于非商业性、个人性、研究性、学习性及非营利性目的使用。严禁商业性使用、再分发及二次创作的商业性利用。详情请见 许可证 请参考文件。

此项目并非官方OpenDART产品。OpenDART是金融监督院的注册商标。