Financial Reports MCP Server

金融报告 MCP 服务

🎬 演示

用于访问 Financial Reports API 的 MCP（Model Context Protocol）服务，提供用于访问公司财务申报文件、行业分类及相关数据的工具和资源。

功能

• 按公司名称、国家或行业搜索公司
• 获取详细的公司信息
• 访问最新的财务申报文件
• 查询行业分类
• 获取申报文件的详细信息和内容

先决条件

• Python 3.11+
• Docker（推荐）
• FastMCP（本地运行时需要）
• dotenv（本地运行时用于管理环境变量）

注意： 为了简洁和可靠，服务现在仅使用真实的 Financial Reports API。所有模拟 API 逻辑和配置均已移除。

🚀 开始使用

有多种方式可以运行此 MCP 服务。请选择以下任一种：

选项 1：Docker（推荐）

推荐使用 Docker 运行 MCP 服务，以确保可复现性、隔离性和易用性。

# Build (once)
docker build -t financial-reports-mcp .

# Run
docker run --rm -i \
  -e API_KEY=your_api_key_here \
  -e API_BASE_URL=https://api.financialreports.eu/ \
  -e MCP_TRANSPORT=stdio \
  financial-reports-mcp:latest

适用于 Docker Compose 用户：

# Copy and configure .env
echo "Copy .env.example to .env and fill in secrets"
cp .env.example .env
# Start services
docker-compose up

对于 Claude Desktop，请使用以下配置。为获得最佳兼容性和安全性，请在 args 中通过 -e 参数传递机密信息：

{
  "mcpServers": {
    "financial-reports": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "API_KEY=your_api_key_here",
        "-e", "API_BASE_URL=https://api.financialreports.eu/",
        "-e", "MCP_TRANSPORT=stdio",
        "financial-reports-mcp:latest"
      ]
    }
  }
}

为什么？ 在 args 中通过 -e 参数传递机密信息，可以确保 Docker 始终能接收到这些信息，无论客户端如何实现环境变量支持。这是 Claude Desktop 及类似客户端最稳健、最通用的方式。

选项 2：Smithery CLI（适用于 Claude）

使用 Smithery CLI 在 Claude 中安装并运行此服务：

npx -y @smithery/cli@latest install \
  @itisaevalex/financial-reports-mcp-server \
  --client claude \
  --key smithery_api_key

选项 3：本地 Python（开发/测试）

1. 安装依赖项：

python -m venv venv           # Create venv
venv\Scripts\activate        # Activate on Windows
pip install -r requirements.txt

2. 运行服务：

python -m src.financial_reports_mcp
# or with uv
uv run src/financial_reports_mcp.py

提示： 如果使用 uv，它会自动从项目根目录加载 .env。

示例

所有示例脚本和配置现在都位于 examples/ 目录中，例如：

• examples/test_server.py — 运行完整的 MCP 测试套件
• examples/docker_claude_config.json — Docker 版 Claude Desktop 配置示例
• examples/uvx_claude_config.json — uv 版 Claude Desktop 配置示例
• examples/python_client_example.py — Python 客户端用法示例

运行测试套件：

python examples/test_server.py

配置

在根目录中创建 .env 文件，并添加以下变量：

API_KEY=your_api_key_here
API_BASE_URL=https://api.financialreports.eu/
MCP_TRANSPORT=stdio

项目结构

• src/ — 源代码目录
  • financial_reports_mcp.py — MCP 服务主入口（所有工具/资源均在此定义）
  • api_client.py — API 客户端工厂
  • real_api/real_client.py — 真实 API 客户端实现
• .env - 环境变量（不纳入 git）
• requirements.txt - 项目依赖项
• Dockerfile & docker-compose.yml - Docker 配置
• setup.py - 软件包安装配置
• install.py - Claude Desktop 安装辅助脚本
• examples/ - 示例脚本和配置
• scripts/ - 安装脚本

可用工具

• get_filing_type(filing_type_id) — 根据申报类型 ID 获取详细信息
• list_industries(industry_group, page, page_size, search) — 列出所有可用的 GICS 行业
• get_industry(industry_id) — 获取 GICS 行业的详细信息
• list_industry_groups(sector, page, page_size, search) — 列出所有可用的 GICS 行业组
• get_industry_group(group_id) — 获取 GICS 行业组的详细信息
• get_sector(sector_id) — 获取 GICS 行业板块的详细信息
• list_sub_industries(industry, page, page_size, search) — 列出所有可用的 GICS 子行业
• get_sub_industry(sub_industry_id) — 获取 GICS 子行业的详细信息
• list_sources(page, page_size) — 列出所有可用的数据源
• get_source(source_id) — 获取数据源的详细信息
• get_processed_filing(processed_filing_id) — 获取申报文件的处理后内容
• get_schema(format, lang) — 获取 API 的 OpenAPI3 架构
• search_companies(params) — 按名称、ISIN、LEI 等搜索公司
• get_company_detail(company_id) — 获取公司的详细信息
• get_latest_filings(params) — 获取最新的财务申报文件
• get_filing_detail(filing_id) — 获取特定申报文件的详细信息
• list_sectors() — 列出所有可用的 GICS 行业板块
• list_filing_types() — 列出所有可用的申报类型

其他资源/辅助工具

• get_sectors_resource() — 以 Markdown 格式列出 GICS 行业板块
• get_filing_types_resource() — 以 Markdown 格式列出申报类型
• get_company_profile(company) — 以 Markdown 格式提供公司简介
• get_company_recent_filings(company, limit) — 以 Markdown 格式列出近期申报文件

提示词

• search_company_by_name() — 按名称搜索公司的提示词
• find_latest_annual_reports() — 查找最新年报的提示词

可用资源

• financial-reports://sectors：所有 GICS 行业板块的列表
• financial-reports://filing-types：所有申报类型的列表
• financial-reports://companies/{company_id}/profile：公司简介
• financial-reports://companies/{company_id}/recent-filings：公司的近期申报文件

示例

示例 1：搜索公司并获取其简介

I want to search for information about Deutsche Bank. Please help me find:
1. Basic company details like country, sector and industry
2. Recent financial filings
3. Key financial metrics if available

示例 2：查找银行的最新年报

I'd like to see the latest annual reports from major European banks. 
Please help me:
1. Find companies in the banking sector
2. Get their latest annual reports
3. Summarize key financial metrics from these reports if available

跨平台兼容性

该服务可在以下平台运行：

• Linux：支持所有方法
• macOS：支持所有方法
• Windows：支持所有方法，但建议在 Claude Desktop 中使用 uv

对于 Windows 用户：

• Claude Desktop 建议使用基于 uv 的安装方式
• Docker 需要 Windows 版 Docker Desktop

故障排除

常见问题

1. 与 Claude Desktop 的通信问题：

   • 配置 Claude Desktop 时，请确保使用 stdio 传输
   • 使用 Docker 时，请确保添加 -i 标志以启用交互模式

2. “Module not found” 错误：

   • 请确保已使用 pip install -r requirements.txt 安装所有依赖项

3. 无法连接到 MCP 服务：

   • 检查服务是否正在运行，并且客户端能否访问

4. API 身份验证错误：

   • 检查 .env 文件中的 API 密钥

日志

直接运行时，日志会输出到控制台。使用 Docker 时，可以通过以下命令查看日志：

docker logs <container-id>

许可证

本项目采用 MIT 许可证，并要求注明 Data Alchemy Labs。详情请参阅 LICENSE。