Capitol Ledger

Capitol Ledger MCP

面向 AI Agent 的国会股票披露只读研究工具。搜索美国众议院官方披露信息，查看已保存的模拟披露账本投资组合，并结合来源和时间背景说明投资组合的变化。

申请试用权限 · API 文档 · PyPI 软件包 · 官方 MCP Registry · 公开虚构示例 · 方法说明

访问权限

此适配器为开源项目。托管数据 API 需要经批准的 Capitol Ledger API 密钥。通过上方链接申请免费 14 天试用。获批的试用账户默认每天可发出 1,000 次经过身份验证的请求，各密钥共享此额度。无需提供付款信息，也不会自动转为付费订阅。提交申请并不意味着您会获得访问权限，也不会让您订阅邮件简报。

公开 JSON 示例为虚构数据，无需密钥即可使用。它适用于查看响应结构，并非真实披露信息或实时数据。

安装

需要 Python 3.12 或更高版本。安装已发布的 PyPI 软件包：

pip install capitol-ledger-mcp

也可以不进行永久安装直接运行：

uvx --from capitol-ledger-mcp capitol-ledger-mcp

如需从此公开代码库安装：

pip install 'git+https://github.com/joalbrecht/capitol-ledger-mcp.git'

连接 MCP 客户端

对于已安装的适配器，请使用以下本地 stdio 配置：

{
  "mcpServers": {
    "capitol-ledger": {
      "command": "capitol-ledger-mcp",
      "env": {
        "CAPITOL_LEDGER_API_URL": "https://capitol-ledger.com",
        "CAPITOL_LEDGER_API_KEY": "YOUR_APPROVED_API_KEY"
      }
    }
  }
}

在本地替换占位符，并将密钥保存在客户端的密钥存储中。请勿将其放入共享提示词、URL、问题单或公开代码库中。如果客户端找不到该命令，请使用其绝对安装路径。

使用 uvx 的客户端也可以设置 "command": "uvx" 和 "args": ["--from", "capitol-ledger-mcp", "capitol-ledger-mcp"]，并使用相同的 env。 这是一个调用托管 HTTPS API 的本地 stdio 服务，不是托管的远程 MCP 端点。无需经纪商或交易账户凭据。

工具

工具	用途	参数
search_disclosures	搜索众议院股票披露信息，提供申报链接和金额范围	可选：ticker、side、available_after、as_of、limit、offset
get_portfolio	获取已保存的模拟账本报告中的期初／期末配置	可选：report_id、as_of
get_portfolio_changes	获取已保存期间的买入、卖出和配置变动	可选：report_id、as_of

连接后可提问示例：

• 过去 30 天披露了哪些 NVDA 买入？请附上来源链接。
• 显示最新保存的模拟披露投资组合及其所属期间。
• 该报告有哪些变化？使用相同的报告 ID。

搜索默认覆盖过去 30 天，每次调用最多返回 100 行。side 接受 purchase、sale 或 exchange。时间戳必须包含时区。使用 meta.next_offset 翻页时，请复用返回的 as_of 和 available_after。固定 report_id，即可比较同一期间的投资组合及其变动。

覆盖范围与解读

• 仅限众议院。 不包含参议院数据。
• 披露信息存在延迟。交易日期、公开文件的可获取时间和收集时间彼此独立；不要将新提交的披露描述为刚刚发生的交易。
• 披露金额为区间值，而非确切的交易金额。合成账本中的数值采用区间中点估算。
• 投资组合快照代表合成披露账本，并非议员的实际持仓，也不是 Capitol Ledger 的可执行策略投资组合。报告可能按日、周、月生成，也可能临时生成；请检查返回的期间元数据。
• 保留来源 URL、计算元数据、时效信息和覆盖范围警告。无法保证数据完整。历史查询使用当前解析的记录，而非解析器或来源修订的完整版本化存档。
• 仅供研究使用；不提供个性化投资建议，也不执行订单。
• 试用访问权限仅用于内部研究工作流；如需再分发数据或向下游用户提供服务，请联系 Capitol Ledger。代码的 MIT 许可证不授予再分发托管数据的权利。

用法与错误

这三个工具共用 API 的账户级配额。可在 MCP 外部通过经过身份验证的 GET /api/v1/account 查询用量和有效期（此操作也会消耗一次调用）。

• 401：密钥无效或已撤销。
• 403：访问权限未激活或已过期。
• 404：该查询没有已完成的保存报告。
• 422：参数无效。
• 429：每日配额已用尽；请参阅 HTTP API 的 Retry-After 标头。

这些工具不会更改订阅、轮换密钥、提交订单，也不会访问本地产品数据库。除本地开发外，API 调用必须使用 HTTPS；重定向时不会携带凭据。密钥是环境凭据，而非工具输入。 模型推理在 MCP 客户端中运行；此适配器仅检索研究数据。

容器选项

提供了一个非 root 容器，用于目录安全性／质量检查，以及偏好使用 Docker 的客户端。请在运行时传入凭据；凭据绝不会打包进镜像。

docker build -t capitol-ledger-mcp .
docker run --rm -i -e CAPITOL_LEDGER_API_KEY -e CAPITOL_LEDGER_API_URL capitol-ledger-mcp

使用 -i 连接 MCP 标准输入／输出；不要分配 TTY。启动服务和列出其工具无需密钥，但数据调用需要密钥。

开发

pip install -e '.[dev]'
pytest
ruff check .

测试使用模拟 HTTP，无需有效凭据，也不会消耗 API 配额。

发布

有关发布工作流、PyPI 可信发布者设置和官方 MCP Registry 元数据，请参阅 PUBLISHING.md。提交到目录并不代表获得背书或获准列入目录。

许可证与联系

适配器代码采用 MIT 许可证。托管 API 的访问权限和数据权利另行处理。 联系方式：[email protected]。