Korean Company Information MCP Server

🏢 韩国企业信息查询MCP服务器

DART API使用的模型上下文协议（MCP）服务器。

AI代理（Claude Desktop、Cursor等）可以实时查询和分析韩国上市企业的财务报表、公告信息、高管信息、股权结构等。

______________________________________________________________________

主要功能

📊 企业信息查询（DART API）

🚀 性能优化

• 战略性缓存：通过24小时缓存企业信息数据，最大限度地减少API调用
• 快速响应：基于缓存的即时响应
• 稳定的运营：错误处理和记录系统
• API密钥优先级：从主服务器收到的密钥→.env文件（用于本地开发）

______________________________________________________________________

🛠️ 技术堆栈

• MCP框架：FastMCP
• 数据验证：Pydantic
• HTTP客户端请求：
• 缓存：cachetools（TTL缓存）
• 异步处理：异步
• 环境：Python dotenv

______________________________________________________________________

📦 安装和设置

1）安装依赖性

pip install -r requirements.txt

💡 uv如果使用： uv sync

2）DART API密钥发放（免费、即时）

1. 电子公示系统Open DART 访问
2. 注册和登录会员
3. 申请/管理认证密钥 从菜单发放验证密钥
4. 立即发放 （免费）

💡 免费，每日API调用限制足够大！

3）设置环境变量

在项目根目录中 .env 创建文件并设置API密钥：

cp env.example .env

.env 文件内容：

DART_API_KEY=your_dart_api_key_here
LOG_LEVEL=INFO
PORT=8097

4）运行服务器

MCP服务器模式（stdio）

python -m src.main

HTTP服务器模式

HTTP_MODE=1 python -m src.main

HTTP服务器默认为 http://localhost:8097在中运行。

______________________________________________________________________

🔌 MCP客户端设置

克劳德桌面

claude_desktop_config.json 将以下内容添加到文件：

设置文件位置：

• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• 苹果电脑: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

设置示例：

{
  "mcpServers": {
    "company-info": {
      "command": "python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/company-info-mcp",
      "env": {
        "DART_API_KEY": "your_dart_api_key_here"
      }
    }
  }
}

⚠️ 重要: cwd 请将路径更改为实际项目路径！

光标

在Cursor的MCP设置中添加上述设置。

______________________________________________________________________

🧰 可用的MCP工具

search_company_tool

按公司名称搜索公司。

参数：

• company_name （必需）：要搜索的公司名称

get_company_overview_tool

查看企业的基本信息。

参数：

• corp_code （可选）：企业唯一编号
• company_name （可选）：公司名称（需要corp_code或company_name之一）

get_financial_statement_tool

查看企业财务报表。

参数：

• corp_code （可选）：企业唯一编号
• company_name （可选）：公司名称
• bsns_year （可选）：业务年度（YYYY格式）
• reprt_code （可选）：报告代码（默认值：“11011”）

analyze_financial_trend_tool

分析公司的财务趋势（最近N年）。

参数：

• corp_code （必需）：企业唯一编号
• years （可选）：要分析的年数（默认值：5，最大值：10）

get_public_disclosure_tool

查看公司的公告信息。

参数：

• corp_code （必需）：企业唯一编号
• bgn_de （可选）：开始日期（YYYYMMDD格式）
• end_de （可选）：结束日期（YYYYMMDD格式）
• page_no （可选）：页码（默认值：1）
• page_count （可选）：每页计数（默认值：10）

get_executives_tool

查看公司的高管信息。

参数：

• corp_code （可选）：企业唯一编号
• company_name （可选）：公司名称
• bsns_year （可选）：业务年度（YYYY格式）
• reprt_code （可选）：报告代码（默认值：“11011”）

get_shareholders_tool

查看股权报告。

参数：

• corp_code （可选）：企业唯一编号
• company_name （可选）：公司名称
• bsns_year （可选）：业务年度（YYYY格式）
• reprt_code （可选）：报告代码（默认值：“11011”）

______________________________________________________________________

📡 HTTP API端点

在HTTP模式下运行时，可以使用以下端点：

健康检查

GET /health
POST /health

查看工具列表

GET /tools

运行工具

POST /tools/{tool_name}
Content-Type: application/json

{
  "company_name": "삼성전자",
  "env": {
    "DART_API_KEY": "your_api_key"
  }
}

______________________________________________________________________

🐳 运行Docker

# 이미지 빌드
docker build -t company-info-mcp:latest .

# 컨테이너 실행
docker run --rm \
  -e DART_API_KEY=your_dart_api_key_here \
  -p 8097:8097 \
  company-info-mcp:latest

______________________________________________________________________

🔑 API密钥优先级

MCP服务器按以下顺序查找API密钥：

1. 优先级1: arguments.env.DART_API_KEY （从主服务器收到的密钥）
2. 优先级2: .env 文件的 DART_API_KEY （用于本地开发）
3. 如果两个都没有的话：健康检查返回“未注册密钥”

通过：

• 生产：从主服务器接收并使用每个用户的密钥
• 本地开发: .env 通过在文件中设置密钥进行开发

______________________________________________________________________

🐛 故障排除

“未设置API密钥”错误

解决方法：

1. .env 在文件中 DART_API_KEY确保正确设置
2. 直接设置为环境变量： export DART_API_KEY=your_key

MCP客户端连接错误

解决方法：

1. 确保服务器运行正常
2. 验证Python路径是否正确
3. 验证是否已安装所有依赖性： pip install -r requirements.txt
4. cwd 将路径更改为实际项目路径
5. Claude Desktop完全关闭后重新启动

______________________________________________________________________

📄 许可证

该项目使用DART API，并遵守DART API的使用条款。