Datavidence Financials

Datavidence Financials — MCP 服务

为每家 SEC XBRL 申报公司提供标准化的 US-GAAP 财务报表——保留特定时点的数据，且与最初申报时一致——作为 MCP 工具供你的 AI Agent 使用（也可使用普通 REST API）。

大模型擅长分析财务报表，却不擅长获取报表。SEC EDGAR 提供了数据，但其中的 XBRL 充斥着不一致的标签、重命名的概念，以及各申报公司的独特差异，因此 Agent 要么会幻觉出数字，要么你得花数周时间构建标准化层。我们提供的正是这一层：你的 Agent 只需查询一家公司的财务数据，就能获得清晰、一致的答案——通过模型上下文协议（Model Context Protocol）或普通的 REST API 获取。

⭐ 如果你觉得这个项目有用，请为仓库点个星。 这是一个由个人维护、尚处早期阶段的项目，星标能帮助其他开发者发现它。

这是 Datavidence Financials API 的开源、AI 原生接入层——一个独立的 stdio 服务，通过 HTTPS 转发请求到 REST API（需自备密钥）。连接器采用 MIT 许可证；底层 API 是商业服务。

30 秒快速试用（无需注册）

使用 uv 运行，无需克隆仓库——它会将程序安装到临时环境中：

FL_API_KEY=sandbox_demo_key uvx datavidence-financials

sandbox_demo_key 无需注册即可返回示例数据，适合首次运行。将 FL_API_KEY 设置为你的真实密钥，即可获取实时 SEC 数据。该服务通过 stdio 使用 MCP，因此 MCP 客户端（例如下文的 Claude Desktop）会启动它。

也可以使用 pipx 将其安装为持久工具：

pipx install datavidence-financials
FL_API_KEY=sandbox_demo_key datavidence-financials

通过 URL 连接（无需安装）

支持远程 MCP 服务（streamable HTTP）的客户端无需安装任何内容即可连接：

URL	密钥	数据
https://mcp.financials.datavidence.ai/mcp	无	示例数据（AAPL 2023 财年）
https://mcp.financials.datavidence.ai/rapidapi/mcp	你的 RapidAPI 密钥，作为 X-API-Key 或 Authorization: Bearer 传入	实时 SEC 数据，由 RapidAPI 按你的套餐计量

Claude Code：

claude mcp add --transport http datavidence-financials \
  https://mcp.financials.datavidence.ai/rapidapi/mcp \
  --header "X-API-Key: YOUR_RAPIDAPI_KEY"

如需使用示例数据，请使用 /mcp URL，并省略请求头。

claude.ai：将 https://mcp.financials.datavidence.ai/mcp 添加为自定义连接器，无需登录。claude.ai 目前尚不能为大多数账户发送 API 密钥，因此暂时会返回示例数据。

差异所在

• 还原当时所见，忠实于原始申报。 传入 as_of 日期，即可获取截至当时的数据——不会因后续重述而产生前视偏差。这正是回测中常常悄然踩到的坑。
• 统一为一种模式。 EDGAR 的 XBRL 标签会因申报者而异，也会随年份变化。我们将其映射到统一的 US-GAAP 损益表、资产负债表和现金流量表中——包括棘手的情况（非控股权益、夹层／临时权益、非日历年度财年）——因此你无需解析申报文件。
• 覆盖所有 SEC XBRL 申报者。 覆盖整个 SEC XBRL 范围（约从 2009 年至今），按需获取并标准化数据——任何拥有 XBRL 事实数据的 CIK 均可，不只是精选子集。
• 同时关联来源。 开启来源信息后，每个值都会附带 SEC accession、申报日期和 EDGAR 直达 URL，让模型引用申报文件，而不是凭空编造数字。

坦诚说明范围：仅支持 US-GAAP（IFRS 申报者会返回明确的“不支持”信号，而不是错误数字）；历史数据覆盖 XBRL 时代（约从 2009 年起）。此外，如果公司重组并采用新的控股实体，SEC 的 ticker 映射只会指向继任者的 CIK——较早年份仍归属于前身实体，因此系统会告知你发生错误，你可以直接传入 cik=。

工具

• get_financials — 从 SEC EDGAR XBRL 获取单家公司某一财年的标准化损益表、资产负债表和现金流量表。 支持 as_of（还原当时所见，忠实于原始申报）、include_provenance（每个值附带 SEC accession、申报日期和 EDGAR 来源直达 URL），以及 include_ratios （利润率、ROA／ROE、杠杆率）。
• get_financials_batch — 一次调用即可获取最多 25 家公司的相同数据 （以逗号分隔的 ticker／CIK）。结果按符号分别返回；只计为一个配额 单位，因此单个错误符号不会导致整个批次失败。
• list_filings — 从 EDGAR 提交索引获取某公司的近期 SEC 申报文件（按时间倒序排列）；可按表格类型筛选（例如 10-K）。调用 get_financials 前，可用它确认哪些 财年有数据。
• get_revisions — 查看某一财年的数据在不同申报文件之间如何发生变化：每个 已申报数值及其申报日期、表格类型、SEC accession 和 EDGAR 链接，还会说明是否发生重述以及变动幅度。Pfizer 的 FY2019 营收在 2020 年申报为 $51.75B，到 2022 年重述为 $40.9B——你可以通过此工具看到这一变化。
• search_companies — 按 ticker 或公司名称查找 ticker 和 CIK；例如，你知道“Berkshire”但需要 BRK-B 时就可以用它。请在使用上面的工具前调用此工具， 因为这些工具都需要标识符。
• get_usage — 查询密钥的月度配额（套餐、已用、剩余、重置时间）。调用 免费；不消耗配额。

错误信息会显示 API 的 recovery_action 提示，帮助 Agent 自动纠正。

Claude Desktop

添加到 claude_desktop_config.json，然后完全退出（Cmd+Q）并重新打开 Claude Desktop——工具就会出现：

{
  "mcpServers": {
    "datavidence-financials": {
      "command": "uvx",
      "args": ["datavidence-financials"],
      "env": { "FL_API_KEY": "sandbox_demo_key" }
    }
  }
}

然后可以提问，例如：“获取 AAPL 的 FY2023 损益表、资产负债表和现金流量表，并附上比率。” 将示例密钥替换为你自己的密钥即可获取实时数据。

Codex

添加到 ~/.codex/config.toml，然后启动 codex——工具就会出现：

[mcp_servers.datavidence-financials]
command = "uvx"
args = ["datavidence-financials"]
env = { FL_API_KEY = "sandbox_demo_key" }
# uvx downloads the package on first run; allow more than Codex's 10 s default.
startup_timeout_sec = 30

将示例密钥替换为你自己的密钥即可获取实时数据。

或者改用 URL 连接（无需安装；将 DATAVIDENCE_API_KEY 设置为你的 RapidAPI 密钥）：

[mcp_servers.datavidence-financials]
url = "https://mcp.financials.datavidence.ai/rapidapi/mcp"
bearer_token_env_var = "DATAVIDENCE_API_KEY"

省略 bearer_token_env_var，并使用 https://mcp.financials.datavidence.ai/mcp 获取示例数据。

配置（环境变量）

变量	默认值	说明
FL_API_KEY	(none)	你的 API 密钥。sandbox_demo_key = 无需注册即可试用（示例数据）。
FL_API_BASE_URL	https://api.financials.datavidence.ai	指向计量 BYOK 访问用的市场网关。
FL_API_KEY_HEADER	X-API-Key	发送密钥时使用的标头（例如，RapidAPI 网关使用 X-RapidAPI-Key）。
FL_API_TIMEOUT	30	每次请求的超时时间，单位为秒。

获取实时数据

演示密钥返回的是示例数据。如需获取实时数据，请在 RapidAPI 上获取密钥：Free（每月 1,500 次调用）、Pro（$29 / 50k）、Business（$99 / 300k）。所有套餐的功能完全一致，区别仅在于每月调用量。

如需使用 RapidAPI 密钥，请设置以下三个变量（在 Claude Desktop 配置的 env 块中，或在 Codex 的 config.toml 中的 env 表中）：

FL_API_BASE_URL=https://datavidence-financials-api.p.rapidapi.com
FL_API_KEY_HEADER=X-RapidAPI-Key
FL_API_KEY=<your RapidAPI key>

你可以在 RapidAPI 上应用的 Authorization 页面中找到密钥，也可以在该 API 页面上的任意代码片段中找到。RapidAPI 会根据你的套餐统计调用量。使用 RapidAPI 密钥时，get_usage 会显示你的 RapidAPI 套餐及其月度限额；调用量由 RapidAPI 统计，请在 RapidAPI 控制面板中查看已使用的调用次数。

从源码运行

pip install -e .
FL_API_KEY=sandbox_demo_key python -m mcp_server.server   # stdio transport

测试

pip install -e ".[dev]"
pytest

共 29 个测试，无需联网或 API 密钥。测试会通过 MCP SDK 调用每个工具，并模拟 HTTP 层；检查 API 错误是否会连同恢复提示一起传递给模型；还会检查每个工具是否都声明了四项行为提示（只读、非破坏性、幂等、开放世界）。

隐私政策

此连接器在你的计算机上运行，不包含遥测功能，也不会存储任何内容。调用工具时，它会向 Datavidence Financials API 发送两类信息：工具参数（例如股票代码、CIK、财年或公司名称搜索）以及请求标头中的 API 密钥。它不会读取你的文件或对话的其余内容。

• **数据去向：**默认发送到 https://api.financials.datavidence.ai。如果将 FL_API_BASE_URL 设置为 RapidAPI 网关，请求会经由 RapidAPI 发送，并受其自身隐私政策约束。
• **API 记录的内容：**对于每个请求，记录其端点、HTTP 状态、响应时间、时间戳和 IP 地址，并关联 API 密钥的哈希值（绝不会记录密钥本身）。
• **保留期限：**使用日志会保留 12 个月。
• **共享：**不会出售；仅与订阅所经由的市场网关以及托管此服务的基础设施提供商共享。
• **联系方式：**[email protected]

完整政策：https://financials.datavidence.ai/privacy

反馈

发现某家公司的数据有误，或者需要某个字段或工具？提交 issue——规范化过程中的边缘情况正是能帮助改进项目的反馈，我会逐一阅读。

链接

• **网站和文档：**https://financials.datavidence.ai
• **MCP 快速入门：**https://financials.datavidence.ai/mcp
• MCP 注册表：ai.datavidence/datavidence-financials
• **PyPI：**https://pypi.org/project/datavidence-financials/
• **获取密钥（RapidAPI）：**https://rapidapi.com/datavidence-ykNLbvGmT/api/datavidence-financials-api
• **隐私政策：**https://financials.datavidence.ai/privacy
• **服务条款：**https://financials.datavidence.ai/terms
• **安全：**如需私下报告漏洞，请参阅 SECURITY.md。

许可证

MIT © 2026 Datavidence LLC — 详见 LICENSE。此连接器为开源软件；底层的 Datavidence Financials API 是商业服务。