FinancialFilings

English | 简体中文

FinancialFilings MCP 服务

适用于 FinancialFilings API 的官方 Model Context Protocol（MCP）服务。 可从 Claude（以及任何兼容 MCP 的客户端）直接访问全球上市公司的监管文件、财务数据和企业信息。默认提供 17 个精选工具（设置 MCP_FULL_SURFACE=1 可启用完整的 55 个工具集）。**所有 FinancialFilings 账户均可免费使用。**数据来自官方监管机构。

---

快速开始

如果你是分析师、研究人员，或任何想向 Claude 查询上市公司文件的人：

1. 创建免费账户：financialfilings.com — 所有 FinancialFilings 用户均可免费使用 MCP 连接器。无需付费套餐。
2. 在 MCP 客户端中添加连接器 — 在下方的连接你的客户端中选择你的客户端。最常用的两种方式：
   • Claude.ai / Claude Desktop：设置 → 连接器 → 添加自定义连接器 → URL：https://mcp.financialfilings.com/mcp
   • Claude Code：claude mcp add --transport http financialreports https://mcp.financialfilings.com/mcp
3. 登录你的 FinancialFilings 账户。完成。

包含截图的完整设置指南：financialfilings.com/integrations/claude/。

---

连接你的客户端

这是一个远程 MCP 服务，使用带 OAuth（PKCE + 动态客户端注册）的 Streamable HTTP。无需复制 API 密钥，也无需保存密钥：连接后会打开浏览器，让你使用 FinancialFilings 账户登录。

端点： https://mcp.financialfilings.com/mcp

请在下方找到你的客户端。如果未列出，请使用末尾的通用配置部分 — 所有客户端的端点和 OAuth 流程都相同，只有配置文件不同。

Claude.ai / Claude Desktop

设置 → 连接器 → 添加自定义连接器 → URL：https://mcp.financialfilings.com/mcp。按提示登录。

Claude Code

claude mcp add --transport http financialreports https://mcp.financialfilings.com/mcp

在会话中运行 /mcp，完成浏览器登录。

或者安装插件，它会添加相同的服务，以及 financial-filings-research 技能（工具速查表和研究工作流）：

/plugin install financialfilings --marketplace financial-reports/financial-reports-mcp-server

对于低于 2.1.275 的 Claude Code 版本，请先添加插件市场：/plugin marketplace add financial-reports/financial-reports-mcp-server，然后运行 /plugin install financialfilings@financialfilings。无论采用哪种方式，都需要运行一次 /mcp 登录。

Codex (OpenAI)

Codex 使用 TOML。添加到 ~/.codex/config.toml（或项目的 .codex/config.toml）：

[mcp_servers.financialreports]
url = "https://mcp.financialfilings.com/mcp"

然后进行身份验证 — 对于支持 OAuth 的服务，Codex 会运行 OAuth 浏览器流程：

codex mcp login financialreports

Cursor

从 Cursor Directory 一键安装，或手动添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "financialfilings": { "url": "https://mcp.financialfilings.com/mcp" }
  }
}

首次使用时会在浏览器中运行 OAuth 流程。

Kilo Code

项目的 .kilocode/mcp.json（或全局 MCP 设置文件）：

{
  "mcpServers": {
    "financialreports": {
      "type": "remote",
      "url": "https://mcp.financialfilings.com/mcp"
    }
  }
}

opencode

opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "financialreports": {
      "type": "remote",
      "url": "https://mcp.financialfilings.com/mcp",
      "enabled": true
    }
  }
}

Gemini CLI

~/.gemini/settings.json：

{
  "mcpServers": {
    "financialreports": { "httpUrl": "https://mcp.financialfilings.com/mcp" }
  }
}

Hermes

Hermes 配置中的 mcp_servers（YAML）：

mcp_servers:
  financialreports:
    url: "https://mcp.financialfilings.com/mcp"
    auth: oauth

通用（适用于任何 MCP 客户端）

大多数支持 MCP 的运行环境都接受 mcpServers 对象。通过 Streamable HTTP 将其指向该端点：

{
  "mcpServers": {
    "financialreports": {
      "type": "streamable-http",
      "url": "https://mcp.financialfilings.com/mcp"
    }
  }
}

支持原生远程 MCP OAuth 的客户端（Claude、Cursor、Windsurf、VS Code、opencode，以及通过 codex mcp login 登录的 Codex）会自动在浏览器中完成登录。对于 OpenClaw 和其他支持 MCP 的运行环境，请使用此配置块，填入连接器 URL，并在提示时完成 OAuth 登录 — 有关确切的文件位置，请参阅客户端自己的 MCP 配置文档。

故障排除：“Client Not Registered”

如果登录时跳转到标题为 Client Not Registered 的页面 — “客户端 ID … 未在服务器的客户端注册表中找到” — 说明客户端提交的注册信息已不在此服务器上。

移除连接器并重新添加。 这是唯一的解决方法，只需几秒钟：

客户端	操作
ChatGPT / OpenAI	设置 → 连接器 → 移除 FinancialFilings（如果在重命名前连接，则名称为 FinancialReports）→ 使用 https://mcp.financialfilings.com/mcp 重新添加并再次登录。
Claude.ai / Claude Desktop	设置 → 连接器 → 移除 FinancialFilings（如果在重命名前连接，则名称为 FinancialReports）→ 重新添加并再次登录。
Claude Code / Codex / Cursor / opencode	移除并重新添加服务（例如，运行 claude mcp remove financialreports，然后重新添加），或再次运行客户端的登录命令（codex mcp login financialreports）。

错误页面本身不会告诉你的两件事：

• 问题不会自行修复，重试也无济于事。 登录在浏览器中进行，因此客户端不会得知登录失败 — 它会一直等待永远不会到达的回调，并不断重放同一个失效 ID。重启也无济于事：托管连接器（ChatGPT、Claude.ai）会在服务器端保留注册信息，因此只有移除连接器才能清除它。
• 你的账户没有问题，也不会影响任何数据。 重新添加会创建新的注册信息，一切都会恢复正常。

如果你在 2026 年 7 月 14 日或之后受到影响： 缓存故障切换导致存储的客户端注册信息丢失。此后登录一直正常 — 只有在该日期之前添加的连接器需要按上述步骤移除并重新添加。

---

可获得的功能

默认提供 17 个可由大模型调用的工具——精选了分析师实际使用的功能：

领域	工具数	用途
公司	5	按名称、股票代码或 ISIN 搜索，获取完整公司档案，获取标准化财务数据，预测下一份年度报告，批量将一组标识符解析为公司 ID
文件	4	列出、获取文件，获取 Markdown 内容（上限为 150K 个字符），在单份文件中进行关键词搜索
ISIN	2	按 ISIN 查询，列出双重上市情况
参考分类体系	2	文件类别和文件类型
账户	1	查看本周期 API 和 MCP 使用费用、支出上限以及剩余免费额度（免费，绝不收费）
指南	3	文件类型分类体系、ISIC 行业分类和 Markdown 获取策略——供无法读取 MCP 资源、仅能使用工具的客户端调用的参考指南

设置 MCP_FULL_SURFACE=1 可恢复完整的 55 个工具：ISIC 部门／分部／组／类别层级、其余参考数据（国家、语言、来源、行项目定义、文件历史记录）、每位用户的关注列表、Webhook 订阅、公司合并审计动态、各交易所的证券上市信息、Agent 账户注册端点（注册、领取密钥、轮换密钥、结账链接、所有者确认、状态）、filings_markdown_search 背后的原始 filings_markdown_search_retrieve 端点，以及 filings_document_retrieve（返回文件，而非 JSON）。

已发布的工具集由一份已提交并经过审核的 FinancialFilings OpenAPI 架构 快照生成（scripts/openapi.snapshot.json，在 CI 和 Docker 构建中通过 FR_PIN_SCHEMA=1 固定），因此结果具有确定性，重建时绝不会悄然发生变化。

配套技能

此代码库附带一项 Agent 技能——financial-filings-research——教 Claude 如何将这些工具组合成分析师实际使用的工作流：公司查询、文件摘要、多公司财务比较、ISIC 行业筛选和文件监控。当用户提及公司名称、股票代码、ISIN、文件类型或财务指标时，该技能会自动启用。

---

架构

┌──────────────────┐     OAuth (PKCE + DCR)      ┌──────────────────┐
│  Claude / MCP    │  ───────────────────────►   │  AWS Cognito     │
│  client          │                              │  (user pool)     │
└────────┬─────────┘                              └────────┬─────────┘
         │  Streamable HTTP /mcp                           │
         │  + bearer token                                 │
         ▼                                                 │
┌──────────────────┐     verify subscription tier          │
│  This server     │  ───────────────────────────────────► │
│  (FastAPI +      │                                       ▼
│   FastMCP)       │     proxy bearer token         ┌──────────────────┐
│                  │  ─────────────────────────►    │  api.            │
│  17 tools        │                                │  financial-      │
│  generated from  │                                │  reports.eu      │
│  OpenAPI schema  │                                │  (first-party)   │
└──────────────────┘                                └──────────────────┘

关键设计决策：

• 工具由生成器生成，而非手工编写。 scripts/generate_mcp_tools.py 读取 OpenAPI 架构——在 CI 和 Docker 构建中通过 FR_PIN_SCHEMA=1 固定为已提交的快照——并生成 src/financial_reports_mcp.py。默认工具集精选为专注的 17 个工具；设置 MCP_FULL_SURFACE=1 则会生成完整工具集。请注意，生成器中的 _PRUNED_EXCLUDE 是一个拒绝列表，因此除非刷新快照的 PR 明确将新的上游端点排除，否则该端点会加入精选工具集。
• 采用 Bearer 令牌代理，而非会话存储。 每次调用时，都会将用户的 Cognito 访问令牌转发给上游 API。服务器端不会存储对话数据，也不会缓存 API 响应。
• 在进程内进行订阅权限检查。 15 秒的 LRU 缓存保存 Cognito sub → 套餐等级映射，避免每次工具调用都请求 FR API。
• 使用同源资源代理。 /favicon.ico、/icon.png、/icon-{32,192,512}.png 均从此源提供（从 CDN 代理并缓存），使连接器 UI 和 /consent 页面无需处理跨源 CSP 限制即可正常渲染。

---

MCP 规范合规性

符合 MCP 2025-11-25 规范：

• ✅ Streamable HTTP 传输 — POST /mcp 会回显 MCP-Protocol-Version，遇到不支持的版本时返回 400
• ✅ OAuth 2.0 — RFC 7591 动态客户端注册 + PKCE S256
• ✅ RFC 9728 受保护资源元数据 — 在 /.well-known/oauth-protected-resource 和 /.well-known/oauth-protected-resource/mcp 均提供
• ✅ 工具注解 — 每个工具都包含 title，以及 readOnlyHint 或 destructiveHint
• ✅ outputSchema — 六个结构化内容工具（companies_list、companies_retrieve、companies_financials_retrieve、filings_list、filings_retrieve、isins_list）
• ✅ Origin 验证 — 对无法识别的 Origin 返回 403；对未经身份验证的请求返回带有正确 WWW-Authenticate 标头的 401
• ✅ 多尺寸连接器图标 — initialize 响应中提供 32×32、192×192、512×512 PNG 图标

CI 会在每个 PR 中验证以上所有项目。

---

工具目录

以下列表会在每次构建时由 scripts/generate_mcp_tools.py 重新生成。请勿手动编辑标记之间的内容。

账户

• usage_retrieve — 获取 API 使用量和支出

公司

• companies_financials_retrieve — 获取公司财务数据
• companies_list — 列出公司
• companies_next_annual_report_retrieve — 预测下一份年度报告
• companies_resolve_create — 按标识符解析公司（批量）
• companies_retrieve — 获取公司详情

文件类别

• filing_categories_list — 列出文件类别

文件类型

• filing_types_list — 列出文件类型

文件

• filings_list — 列出文件
• filings_markdown_retrieve — 获取文件 Markdown
• filings_retrieve — 获取文件详情

ISIN

• isins_list — 列出 ISIN
• isins_retrieve — 获取 ISIN

---

示例提示词

连接后，请尝试：

• “查找 Apple 最近的 10-K，并总结风险因素相较上一年度的变化。”
• “获取 ASML 的完整公司详情。”
• “比较 Iberdrola、Engie、Enel、RWE 最近一个财年的净债务。”
• “列出过去 6 个月提交年度报告的欧盟航空公司。”
• “显示 Tesla 过去 30 天的内部人交易文件。”
• “当关注列表中的任何公司提交 8-K 时提醒我。”
• “Volkswagen AG 的 LEI 是什么？”

---

自托管

自托管需要自行搭建 AWS Cognito 用户池，主要适用于分叉项目并将其改造为使用其他上游 API。对于 FinancialFilings API，推荐使用托管服务 mcp.financialfilings.com。

详细的自托管文档（Docker、Cognito 设置、环境变量、CDN/图标配置）：docs/SELF-HOSTING.md。

---

开发

一键初始化（venv → 依赖项 → 环境检查 → 生成 → 运行）：

cp .env.example .env   # fill in Cognito values first; see docs/SELF-HOSTING.md
make dev               # creates .venv, installs, validates env, regenerates, serves on :8000
# MCP endpoint: http://localhost:8000/mcp

或分步操作：

# 1. Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -r requirements-test.txt

# 2. Configure
cp .env.example .env  # then fill in Cognito values; see docs/SELF-HOSTING.md

# 3. Generate the MCP module from the OpenAPI schema
python scripts/generate_mcp_tools.py

# 4. Run tests
pytest

# 5. Run locally
python -m uvicorn src.financial_reports_mcp:app --host 0.0.0.0 --port 8000
# MCP endpoint: http://localhost:8000/mcp

CI 会在每个 PR 中运行完整的单元测试套件，以及 Docker-Compose 端到端测试（使用 Redis）。请参阅 .github/workflows/ci.yml。

使用个人 API 密钥进行本地开发

如需针对真实后端迭代生成器、工具或提示词，且无需每次重启都经过 Cognito OAuth 流程，服务支持仅用于开发的 DEV_MODE_API_KEY 环境变量。设置该变量后，现有 /mcp 端点会跳过 JWT 验证（包括 subscription_required 和 _authorize_or_raise 路径），并将密钥作为 X-API-Key 转发至 API_BASE_URL。

这只是为维护者提供的便利，并非生产环境的身份验证方式。 如果 MCP_BASE_URL 包含生产主机名（mcp.financialfilings.com），模块将拒绝导入。

1. 将你的个人 FinancialFilings API 密钥添加到 .env：

   DEV_MODE_API_KEY=fr_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   MCP_BASE_URL=http://localhost:8000
   

2. 重新生成并启动服务（仍必须设置 Cognito 变量——即使启用了绕过机制，OAuth 代理模块也会加载）：

   make regen
   python -m uvicorn src.financial_reports_mcp:app --host 0.0.0.0 --port 8000 --reload
   

3. 将 Claude Code 指向本地实例：

   claude mcp add --transport http financialfilings-local http://localhost:8000/mcp
   

   请像这样为每位开发者单独添加，而不要添加到仓库的 .mcp.json 中：该文件仅列出生产服务，因为扫描此仓库的目录（例如 Cursor Directory）会将其中的每个条目都作为公开安装项展示。

生产环境的无头模式 / API 密钥身份验证（通过并行的 /mcp/apikey 端点，在每个请求中传递 X-API-Key）已记录在 #28 中，是一项独立于此开发模式快捷方案的功能。

常见任务

# Regenerate tools after the OpenAPI schema changes
python scripts/generate_mcp_tools.py

# Run only fast unit tests
pytest tests/test_*.py

# Run end-to-end tests with Redis (requires Docker)
make e2e

---

评估变更

此服务由 financial-reports/mcp-evals（私有仓库）进行基准测试。跨模型评分卡（任务成功率、工具选择准确率、路径一致性、令牌数 / 轮数 / 延迟）位于该仓库，而非此处。合并对工具描述、Prompts 或生成器的变更前，请使用生产环境或本地开发 MCP 运行测试框架，并比较评分卡。

此仓库包含的内容：位于 tests/eval/ 的确定性提示词注册测试——运行快速、无需 API 密钥，并会在每个 PR 上运行。跨仓库工作流请参阅 tests/eval/README.md。

---

安全

此服务会处理 OAuth 流程和 Bearer 令牌。发现漏洞？请不要公开提交问题。 负责任披露流程请参阅 SECURITY.md。

服务端保障：

• Bearer 令牌按请求代理，绝不记录日志或持久化。
• 强制使用 HTTPS（边缘节点会将 HTTP 重定向至 HTTPS）。
• 对 HTML 响应应用 CSP（default-src 'none'，仅允许同源资源）。
• 来源验证会拒绝来自未识别来源的请求。
• 所有加密操作都依赖标准库和 AWS SDK；不使用自定义加密算法。

---

贡献

欢迎贡献。开发环境设置、重新生成→测试→PR 工作流，以及欢迎提交的变更类型（测试、文档、生成器改进、在 scripts/generate_mcp_tools.py 中手动调整的工具描述）和会被拒绝的内容（手动编辑 src/financial_reports_mcp.py——该文件由自动生成，并会在每次构建时被覆盖），请参阅 CONTRIBUTING.md。

---

项目状态

• 生产环境：已在 https://mcp.financialfilings.com/mcp 上线
• 已收录于：Claude connector directory、Cursor Directory
• 规范合规性：MCP 2025-11-25
• 已测试：Claude.ai、Claude Code、Claude Desktop、Cursor、Windsurf。另提供 Codex、Kilo Code、opencode、Gemini CLI 和 Hermes 的配置片段（参见连接客户端）。

---

许可证

MIT — © FINANCIALREPORTS PTE. LTD.

---

致谢

特别感谢 @itisaevalex 提供最初由社区构建的 MCP 服务，它作为概念验证，促成了这个官方版本的诞生。

本项目基于 FastMCP、FastAPI 和 Model Context Protocol 构建。