Usa Spending

USA Spending MCP 服务

这是一个无状态的可流式 HTTP MCP 服务，用于与 USASPENDING.gov 交互。USASPENDING.gov 是政府支出数据的官方来源。 你可以追踪政府支出的变化、按机构搜索政府支出、了解政府在各社区的支出等。 USASPENDING.gov 提供了这个实用的仪表板，展示了 API 的部分功能，方便你大致了解通过此 API 可以实现哪些功能。 API 文档可通过此 URL 查看。

本地运行

uv run src/server.py

从 PyPi 运行

uvx --from usaspending-mcp-server@latest usaspending-mcp-server

从 Docker 运行

docker build -t usaspending-mcp-server .
docker run -p 8000:8000 usaspending-mcp-server

与 Claude Desktop 配合使用

使用以下配置更新 claude_desktop_config.json。 确保 MCP 服务已通过上述任一方法启动。

{
  "mcpServers": {
    "usaspending": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp"
      ]
    }
  }
}

配置选项

可使用以下环境变量或 .env 变量，自定义 MCP 服务运行的主机和端口。

MCP_SERVER_HOST
MCP_SERVER_PORT

工具

名称	描述	提示词示例
federal_accounts	使用此工具可以更好地了解各机构如何接收并使用国会拨款来开展其计划、项目和活动。	- 请详细说明国土安全部如何使用资金。
list_budget_functions	此工具会按标题排序，返回所有预算职能的列表	- 政府在社区与区域发展方面的支出与国际事务方面的支出各是多少？
major_object_class	此数据可用于更好地了解特定机构使用资金的不同方式	- 教育部在员工薪酬和福利方面支出了多少？
recipient	此工具可用于直观查看与特定接收方相关的政府支出。它会返回接收方的列表、级别、DUNS、UEI 和金额。	- 有哪些公司获得了 NSA 的资金？
spending	此数据可按详细程度深入查看特定数据子集。它表示指定时间段内的所有政府支出，并按所选数据类型分组。	- 请按机构列出普通科学、太空和技术领域的支出。
spending_by_award	此工具支持对特定支出数据子集进行复杂筛选。它接受筛选条件和字段，并返回经过筛选的奖励项目字段。	- 2025 年金额最高的奖励项目是什么？ - Lindsey Graham 选区内有哪些公司获得了联邦重要合同？
spending_over_time	此工具会返回按时间段分组、按升序排列（从最早到最近）的汇总奖励金额列表。	- 过去 5 年，加利福尼亚州的支出有何变化？
subawards	此工具会返回经过筛选的子奖励项目集合	- 请描述 CONT_AWD_FA870221C0001_9700_-NONE-_-NONE- 的一些子奖励项目，并说明这些项目的理由。
total_budgetary_resources	此工具用于提供有关政府联邦预算资源的信息	- 2025 年与 2024 年的政府预算分别是多少？ - 联邦政府总共向各政府机构提供了多少资金？
toptier_agencies	此数据可用于更好地了解特定机构使用资金的不同方式	- 哪个联邦机构获得的资金最多？

工具目录说明

由于每个工具本质上都是 API 路由的封装，因此每个工具的映射方式与 usaspending-api 的 api_contracts 目录结构类似。 不过，对于 federal_accounts、recipient、spending 和 subawards 这些工具，其 API 映射对应的是根目录 api_contracts/v2 中提到的契约。 每个工具都有一个 md 文件，方便查阅用于创建该工具的文档。 这些契约在 usaspending-api 中很少更新，但仍应进行检查，确保它们是最新的。 目前，所有契约（即 API 文档）均引用自 usaspending-api 的提交 dv551d0。

测试

MCP Inspector 是一种很好的方式，可在不连接大模型的情况下测试输入和输出架构。 此外，还有一个示例 MCP 客户端，可用于使用 OpenAI 测试应用程序。 还有各种单元测试，重点测试工具处理程序、输入／输出架构以及对 USASpending API 的 HTTP 调用。 可以通过以下命令运行这些测试。

uv run pytest

贡献

请先参阅测试部分，在提交 PR 前测试你的更改。 如果要添加新工具，请同时添加相应契约的副本，作为创建 inputSchema 和 outputSchema 时的参考。 请将工具添加到 usaspending_api 契约目录中对应的相同路径下。 文件命名规范请参考契约文件名，工具也使用相同的名称。 例如，如果你要为 v2/disaster/spending_by_geography.md API 路由创建工具，应将该工具添加到 tools/v2/disaster/spending_by_geography.py 路径下，并将工具命名为 disaster_spending_by_geography。 如果对此有任何异议，请在 PR 中说明原因，因为这并非万无一失！

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。