财务报告MCP服务器

Name: 财务报告MCP服务器
Author: itisaevalex

作者：itisaevalex7 星标更新：2025-04-18

安装使用来源：spider==github.com

项目介绍

财务报告 MCP 服务器

🎬 演示

这是一个用于访问财务报告 API 的 MCP（模型上下文协议）服务器，提供工具和资源以访问公司财务申报、行业分类及相关数据。

特性

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

先决条件

Python 3.11+
Docker（推荐）
FastMCP（如果本地运行）
dotenv 用于环境变量管理（如果本地运行）

注意： 该服务器现在仅使用真实的财务报告 API。为了简化和可靠性，已移除所有模拟 API 逻辑和配置。

🚀 快速开始

有多种方式可以运行此 MCP 服务器。选择以下选项之一：

方案 1：Docker（推荐）

Docker 是推荐的方式，因为它具有可重复性、隔离性和易用性。

# 构建（一次）
docker build -t financial-reports-mcp .

# 运行
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 用户：

# 复制并配置 .env
echo "复制 .env.example 到 .env 并填写密钥"
cp .env.example .env
# 启动服务
docker-compose up

对于 Claude Desktop，请使用以下配置。将密钥作为 -e 参数传递给 args 以确保最大兼容性和安全性：

{
  "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-re reports-mcp:latest"
      ]
    }
  }
}

为什么？ 将密钥作为 -e 参数传递给 args 可确保 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（开发/测试）

安装依赖项：

python -m venv venv           # 创建虚拟环境
venv\Scripts\activate        # 激活（在 Windows 上）
pip install -r requirements.txt

运行服务器：

python -m src.financial_reports_mcp
# 或者使用 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) — 获取 G_ICS 子行业的详细信息
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：搜索公司并获取其概况

我想查询关于德意志银行的信息。请帮我找到：
1. 基本公司详情，如国家、部门和行业
2. 最近的财务申报
3. 如果有的话，关键财务指标

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

我想查看主要欧洲银行的最新年度报告。
请帮我：
1. 找到银行业部门的公司
2. 获取他们的最新年度报告
3. 如果有的话，总结这些报告的关键财务指标

跨平台兼容性

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

Linux：支持所有方法
macOS：支持所有方法
Windows：支持所有方法，但建议使用 uv 进行 Claude Desktop 安装

特别针对 Windows 用户：

对于 Claude Desktop，建议使用基于 uv 的安装
Docker 需要 Docker Desktop for Windows

故障排除

常见问题

与 Claude Desktop 的通信问题：
- 确保在配置 Claude Desktop 时使用 stdio 传输
- 对于 Docker，确保包括 -i 标志以启用交互模式
“模块未找到”错误：
- 确保通过 pip install -r requirements.txt 安装了所有依赖项
无法连接到 MCP 服务器：
- 检查服务器是否正在运行且可以从客户端访问
API 认证错误：
- 在 .env 文件中验证您的 API 密钥

日志

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

docker logs <container-id>

许可

该项目根据带有 Data Alchemy Labs 归属要求的 MIT 许可证发布。详情请参阅 LICENSE。