Financial Reports MCP Server

财务报告MCP服务器

🎬 演示

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

特性

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

先决条件

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

注： 服务器现在只使用真实的财务报告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，请使用以下配置。 传递秘密 -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-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（开发/测试）

1. 安装依赖项：

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

1. 运行服务器：

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桌面配置示例
• examples/uvx_claude_config.json --uv的Claude桌面配置示例
• 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：支持所有方法
• 视窗：支持所有方法，但使用 uv 建议用于Claude Desktop

特别是Windows用户：

• 对于Claude Desktop，建议使用基于紫外线的安装
• Docker需要Windows版的Docker桌面

故障排除

常见问题

1. 与Claude Desktop的沟通问题:

- 确保在配置Claude Desktop时使用stdio传输 - 对于Docker，请确保包含 -i 交互模式标志

1. “找不到模块”错误:

- 确保所有依赖项都已安装 pip install -r requirements.txt

1. 无法连接到MCP服务器:

- 检查服务器是否正在运行并且可以从客户端访问

1. API的身份验证错误:

- 在中验证您的API密钥 .env 文件

日志

直接运行时，日志会输出到控制台。对于Docker，您可以通过以下方式查看日志：

docker logs 

许可证

该项目根据麻省理工学院许可证获得许可，对数据炼金术实验室有归因要求。看 许可证 了解详情。