Hub-Equity MCP

hub-equity-mcp

面向 LLM Agent 的标准化 XBRL 财务数据。 一个 Model Context Protocol (MCP) 服务，可向 Claude Desktop、Cursor 及任何兼容 MCP 的客户端提供来自美国 SEC (EDGAR) 和欧洲 ESEF 申报文件的标准化财务事实。

Hub-Equity 通过统一的 hub 概念词汇，在提供美国 SEC 数据的同时提供标准化的 欧洲 ESEF 申报数据，因此 Agent 可以查询 REVENUE 或 TOTAL_ASSETS，无论发行人向 SEC 申报还是按 ESEF 申报，都能获取可比较且带来源链接的数值。

成熟度。 此连接器背后的公共 REST API 已在生产环境运行，并为 Hub-Equity 自有聊天服务提供支持。该软件包遵循语义化版本规范；由于其安装用户群仍较小，目前仍保留 Beta 分类器。

为什么选择它

• 两种监管体系，共用一种词汇。 SEC us-gaap 和 ESEF ifrs-full 概念会映射到一组标准化 hub 代码，因此可以开箱即用地跨发行人、跨分类体系进行比较。
• 每个数字都有来源链接。 财务事实包含其申报文件、期间和来源信息，Agent 可以据此引用，而不是猜测。
• 感知重述。 识别明确的修订和未明示的重述（后续申报文件重新列示了不同数值，但未提交修订文件），并将每项变更与产生该变更的申报文件关联。
• 只读且封闭世界。 根据 MCP 规范，每个工具都声明 readOnlyHint=true、idempotentHint=true、destructiveHint=false、openWorldHint=false，因此客户端无需自省即可判断安全性和缓存策略。
• 无需数据库凭据。 已发布的软件包只通过 HTTPS 访问公共 REST API（https://api.hub-equity.com），不会随包提供或要求数据库密钥。

安装

pipx run hub-equity-mcp

pipx run（或 uvx hub-equity-mcp）会在隔离环境中获取并启动服务；pip install hub-equity-mcp 也可使用。需要 Python 3.12 或更高版本。

身份验证与访问权限

该服务只与公共 REST API 通信，访问该 API 需要 hubq_ 密钥（环境变量 HUBEQUITY_API_KEY）。

• 免费密钥。 在 https://hub-equity.com/settings/api-keys 注册账户并创建密钥，只需一分钟。可使用基础工具集（实体搜索、标准化财务事实、时间序列、分部、筛选器、数据质量评级、外汇换算等）。
• 付费方案。 可解锁高级工具（重述差异、计算树、跨期间比较、跨发行人比较、验证检查、扩展概念），并提高速率限制。请参阅下表。

已发布的软件包不会直接访问数据库，只会访问 REST API。

配置客户端

Claude Desktop

在 claude_desktop_config.json 中添加 （macOS：~/Library/Application Support/Claude/claude_desktop_config.json， Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

如果未设置 HUBEQUITY_API_KEY，每次工具调用都会返回 HUBEQUITY_API_KEY is not set，并附上获取免费密钥的链接。

Cursor

在 .cursor/mcp.json（项目根目录）或 Cursor 全局 MCP 设置中添加：

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

环境变量

• HUBEQUITY_API_KEY（必需）：hubq_ 密钥。免费密钥可使用基础工具；付费方案可使用高级工具并获得更高的速率限制。
• HUBEQUITY_API_URL（可选）：默认为 https://api.hub-equity.com。 设置密钥时，必须使用 https://（服务不会向非回环主机通过明文传输 Bearer 密钥）。

功能

类型	内容
工具	只读工具：发现、财务事实、时间序列、分部、取证检查（见下表）
资源	Hub 目录、报表架构、层级目录、使用指南、覆盖范围快照
提示词	分析模板（见下方列表）
补全 API	{hub_code} 自动补全

工具

机器可读的分级目录以资源形式提供 （hub-equity://catalog/tool-tiers）。Free 工具涵盖发现和身份信息；Pro 工具在所有付费套餐（Builder、Team、Enterprise）中均可使用，可提供更深入的取证分析（计算树、修订和静默重述的差异、跨期比较、跨发行方比较、验证结果、扩展概念）。工具的分级与其调用的 REST 端点一致：每个 Pro 工具的端点都要求服务器端具备 facts.premium 作用域，而 Free 限制（get_fact_decomposition 深度为 1，且不含汇总组件或维度切片；screen_companies 最多返回 20 条结果，且不含质量筛选器；get_segments 返回坐标轴，不含成员；roll_up_metric 返回数值，不含规则）由 API 执行，而不仅限于此软件包。

工具	级别	功能
find_entity(query)	免费	按名称、股票代码或 CIK 搜索。返回其他工具所需的 entity_id。
get_fact(entity_id, hub_concept_code, fiscal_year, fiscal_period_type?)	免费	返回一个标准化数值及其申报来源。
get_fact_decomposition(entity_id, fiscal_year, hub_concept_code? or qname?, depth?)	免费（深度为 1，仅限 linkbase）/ 专业版（深度为 2–3）	Hub 汇总、XBRL 计算 linkbase 子项和维度拆分。免费版：提供 linkbase 层，不含汇总组成项和维度切片。
search_concept(query)	免费	根据标签或部分代码查找 hub 代码。
list_hubs(category?, include_non_primary?, limit?)	免费	按类别列出标准化 hub 目录。
get_entity_profile(entity_id)	免费	行业、审计机构、员工人数、财年末和近期申报文件。
get_metric_history(entity_id, hub_concept_code, n_years?)	免费	返回 N 年时间序列，包括同比增长率和 CAGR。
get_segments(entity_id, hub_concept_code, fiscal_year)	免费（有上限）	按维度轴／成员拆分（分部、地理区域）。免费版：提供维度轴，不含成员；专业版：提供所有成员。
get_amendments(entity_id, fiscal_year?)	免费	10-K/A 重述摘要：每份修订及其按概念列出的变更（每份修订 50 项）。
get_silent_restatements(entity_id, fiscal_year?)	免费	静默重述：后续申报文件在比较列中重新列示、但数值有所不同且未提交修订文件的数据；按揭示这些变更的申报文件分组（每份申报文件 50 项变更）。
compare_entities(entity_ids, hub_concept_codes, fiscal_year)	专业版（最多 10×10）	对齐日历年度后，生成单一期间的跨发行方对比矩阵。接受 UUID、股票代码或 TICKER.MIC。
roll_up_metric(entity_id, hub_concept_code, fiscal_year)	免费（有上限）	当数值没有直接标注时，根据带符号的子项计算数值。免费版：提供数值；专业版：提供规则及其背后的带符号贡献项。
convert_currency(amount, from_currency, to_currency, date?, rate_type?)	免费	使用 ECB 参考汇率进行货币换算（收盘价、年初至今平均值、上一年度平均值）。
screen_companies(country?, sector?, min_revenue?, ..., sort_by?, limit?)	免费（上限为 20，无质量筛选）/ 专业版（上限更高）	按元数据、收入、审计和数据质量筛选发行方范围。
get_amendment_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)	专业版	按概念列出 10-K/A 差异：重要性、类型和概念筛选条件、标签、绝对差值，以及作为来源的两份申报文件。
get_silent_restatement_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)	专业版	提供静默重述的同类差异。
get_calculation_tree(filing_id, link_role?)	专业版	申报文件的计算 linkbase：列出每个总计及其组成项，并同时显示声明的符号和申报数值所支持的符号。
compare_filings(entity_id, fiscal_year_a, fiscal_year_b, hub_concept_codes?)	专业版	对同一实体的不同时期进行对比，并标记新增／移除／符号翻转／重述。
get_extension_concepts(entity_id, status_filter?, limit?)	专业版	列出发行方在标准分类体系之外声明的专属 qname。
get_data_quality_grade(entity_id)	免费	A+ 至 D 等级（也可能没有等级）、决定等级的两项门槛及其计数、新鲜度、直接值与推导值的占比。
get_validation_results(filing_id?, entity_id?, fiscal_year?, status_filter?)	专业版	XBRL 会计检查和计算 linkbase 检查结果。

资源

URI	类型	用途
hub-equity://catalog/hubs	json	完整的标准化枢纽目录，包含 EN/FR 标签和类别。
hub-equity://catalog/categories	json	每个类别的枢纽数量。
hub-equity://catalog/tool-tiers	markdown	免费与 Pro 工具目录及使用限制条件。
hub-equity://schema/financial-statements	markdown	报表结构和阅读规则。
hub-equity://catalog/hub/{hub_code}	template	单个枢纽的前向目录条目。
hub-equity://entity/{entity_id}/profile	template	实体完整快照。
hub-equity://prompts/best-practices	markdown	面向客户端集成的系统提示词指南。调用任何工具前请先加载。
hub-equity://prompts/tool-usage-examples	markdown	各工具的少样本示例（正例和反模式）。
hub-equity://prompts/data-coverage	json	实时数据集快照（发行人和申报文件数量、来源、分类体系、财年范围）。缓存 24 小时。

提示词

八种分析模板：peer_comparison、quality_of_earnings、 restatement_audit、sector_overview、valuation_screen、 goodwill_impairment_risk、working_capital_diagnostic、cash_flow_consistency。

面向客户端开发者

调用任何工具前，请先获取 hub-equity://prompts/best-practices，并将 其中的 Markdown 注入系统提示词。这能让你的客户端遵循与 Hub-Equity 自有聊天 相同的工具路由、来源引用和数值保真规则。

# Pseudo-code for a typical MCP client integration
session = mcp.connect("hub-equity-mcp")
best_practices = session.read_resource("hub-equity://prompts/best-practices")
system_prompt = "You are an assistant ...\n\n" + best_practices
# now call session.call_tool("find_entity", {"query": "AAPL"}) etc.

速率限制

模式	限制	备注
Free key	每分钟 120 个请求	基础工具。
Builder key	每分钟 300 个请求	已解锁高级工具。
Team key	每分钟 600 个请求	已解锁高级工具。
Enterprise key	每分钟 1 000 个请求	可协商。

每个 API key 单独计数。

对于每分钟触发的 429，客户端会先以指数退避方式重试（最多 3 次）， 然后抛出 RateLimitExceeded。每日或每月额度用尽时，会立即抛出错误，并附上 API 的消息。

故障排除

现象	原因	解决方法
429 Too Many Requests / RateLimitExceeded	达到速率上限（Free key 每分钟 120 次，付费 key 每分钟 300 至 1 000 次）	升级到付费套餐，或降低工具调用的并发扇出。客户端已实现最多 3 次退避重试。
每次工具调用都提示 HUBEQUITY_API_KEY is not set	客户端的 env 块中没有密钥	设置 HUBEQUITY_API_KEY；获取 Free key 只需一分钟：https://hub-equity.com/settings/api-keys。
HubEquityRestError: HTTP 401	hubq_ key 无效、已过期或已撤销（INVALID_API_KEY）	在 https://hub-equity.com/settings/api-keys 创建新密钥。
HubEquityRestError: HTTP 403	密钥所属工作区使用 Free 套餐，但调用需要 Pro 工具，或超出 Free 限制（depth > 1、limit > 20、min_quality_grade）	升级套餐，或遵守 Free 限制。
RateLimitExceeded 的响应正文包含 DAILY_QUOTA_EXCEEDED / MONTHLY_QUOTA_EXCEEDED	工作区的用量额度已用尽（Free 每天 200 次 / 每月 5 000 次，Builder 每月 50 000 次，Team 每月 500 000 次）；立即抛出，不重试	等待 resets_on 指定的时间，或升级套餐。
连接错误或超时错误	网络无法连接到 api.hub-equity.com，或 HUBEQUITY_API_URL 配置错误	检查网络连接；确认 HUBEQUITY_API_URL（若已设置）指向可访问的 https:// 主机。
ValueError: HUBEQUITY_API_URL must use https://	已设置密钥，但 URL 在非回环主机上使用了纯 http://	使用 https://，或取消设置 HUBEQUITY_API_URL，以回退到默认 API。
Claude Desktop 或 Cursor 中未显示服务	配置 JSON 错误，或 pipx 不在客户端的 PATH 中	验证 JSON；如果客户端无法解析路径，请使用 pipx（或 uvx）的绝对路径。

本地运行

python -m hub_equity_mcp.server

或者使用 MCP inspector 交互式操作：

npx @modelcontextprotocol/inspector python -m hub_equity_mcp.server

inspector 会列出所有工具、资源和提示词，并允许你逐一调用。

开发

pip install -e '.[dev]'
pytest tests/

测试是隔离的：工具测试使用 respx 模拟 REST API，因此无需连接实时后端。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。此连接器是面向公开 Hub-Equity REST API 的开源客户端；高级数据的访问仍由服务端通过 API 密钥、套餐和速率限制进行控制。