Usaspending Gov Mcp

usaspending-gov-mcp

适用于 USAspending.gov API 的免费开源 MCP 服务：涵盖合同、拨款、贷款、分包、受款方、机构和联邦账户。

概览、演示视频和托管设置：https://1102tools.com/mcp/usaspending

无论本地运行还是托管运行，都不需要 API 密钥。请参阅本地或托管。

回归测试包含对 USAspending API 的实时检查。2026 年 10 月发布的版本还通过了涵盖全部 55 个工具的真实合同问题测试（奖励历史、财政年度总额、分包报告、联邦账户）。请参阅 testing.md。

本地或托管

本地（桌面）	Claude（托管）	ChatGPT（托管）
本地设置	安装	安装

• 本地会在你的电脑上运行，可在 Claude 或 ChatGPT 桌面应用或其他 AI 应用中使用。你将获得自己的完整速率限制，并且只依赖政府服务。它不会自动更新，因此请让你的 AI 为其更新。你无需手动设置：将此页面的链接发给你的 AI，并让它帮你设置或指导你完成设置。
• 托管版本始终保持最新，无需设置或密钥，可在任何地方的 Claude 或 ChatGPT 中使用。

比较本地和托管 · 匹配提示词

功能简介

将 USAspending.gov REST API 以 55 个 MCP 工具的形式对外提供，涵盖：

搜索与聚合

• search_awards - 针对合同、IDV、拨款、贷款、直接支付的主要搜索
• program_numbers 过滤器 - 将拨款、贷款及其他援助缩小到某个援助清单（CFDA）编号，例如 Medicaid 的 93.778。适用于 search_awards、get_award_count、spending_over_time、spending_by_category、spending_by_subaward_grouped、spending_by_transaction 和 spending_by_geography。可通过 autocomplete_cfda 按项目名称查找编号。
• get_award_count - 跨奖励类别的维度计数
• spending_over_time - 时间序列聚合（财年、季度、月）
• spending_by_category - 按机构、供应商、NAICS、PSC、州等维度的 Top N 细分
• spending_by_transaction - 修改级别的交易搜索
• spending_by_geography - 按州、县或国会选区细分
• new_awards_over_time - 某个受赠方的项目管道趋势

奖励详情

• get_award_detail - 单笔奖励的完整记录
• get_transactions - 某笔奖励的完整修改历史
• get_award_funding - File C 资金数据（财政部账户、对象类别、项目活动）
• get_award_funding_rollup - 单行资金汇总
• get_award_subaward_count、get_award_federal_account_count、get_award_transaction_count
• get_idv_children - IDV 下的任务订单/交付订单
• awards_last_updated - 数据新鲜度检查

子奖励（FFATA）

• search_subawards - 单个主奖励下的子奖励
• spending_by_subaward_grouped - 将匹配的主奖励与累计上报的子奖励总额对应起来

受赠方

• search_recipients - 按关键词搜索受赠方
• get_recipient_profile - 完整的受赠方记录
• get_recipient_children - 母公司受赠方的子公司
• autocomplete_recipient - 按部分名称查找受赠方名称
• list_states - 所有州及其 FIPS 代码

对于受赠方工作流，可从 autocomplete_recipient 获取名称并传给 search_recipients。使用返回的 id 哈希查询档案和新奖励 趋势。要检索子公司，请将父级（-P）行的 uei（或 旧版 duns）传给 get_recipient_children；该工具接受 UEI/DUNS。

机构深度

• list_toptier_agencies、get_agency_overview、get_agency_awards
• get_agency_budgetary_resources - 按财年的预算资源
• get_agency_sub_agencies - 带承付义务的下属组织
• get_agency_federal_accounts - 资金来源（TAS）
• get_agency_object_classes - 支出类别（OMB）
• get_agency_program_activities - 项目级细分
• get_agency_obligations_by_award_category - 合同与拨款的构成

IDV 深度

• get_idv_amounts - IDV 顶层汇总
• get_idv_funding、get_idv_funding_rollup - IDV 的 File C
• get_idv_activity - IDV 下的子订单

联邦账户（财政部）

• list_federal_accounts - 搜索 TAS
• get_federal_account_detail、get_federal_account_object_classes、 get_federal_account_program_activities、get_federal_account_fy_snapshot

自动补全

• autocomplete_psc、autocomplete_naics
• autocomplete_awarding_agency、autocomplete_funding_agency
• autocomplete_cfda（拨款）、autocomplete_glossary、autocomplete_recipient

参考数据

• get_naics_details、get_psc_filter_tree
• get_award_types_reference - 所有奖励类型代码（A=BPA Call 等）
• get_def_codes_reference - 灾难应急基金代码（COVID、IIJA、IRA）
• get_glossary - 采购/支出词汇表
• get_submission_periods - 机构报告期覆盖范围
• get_state_profile - 州级支出档案

工作流便利工具

• lookup_piid - 自动检测合同还是 IDV，并返回匹配的奖励

安装

通过 pip

pip install usaspending-gov-mcp

通过 uvx（推荐，无需 venv）

uvx --refresh-package usaspending-gov-mcp --from usaspending-gov-mcp usaspending-mcp

此服务需要 --from 参数，且仅此服务需要。PyPI 包为 usaspending-gov-mcp，但它安装的控制台脚本是 usaspending-mcp， 因此直接运行 uvx usaspending-gov-mcp 会失败，并报错 "An executable named usaspending-gov-mcp is not provided by package usaspending-gov-mcp"。

也不要运行 uvx usaspending-mcp。usaspending-mcp 是 PyPI 上一个 无关的第三方包，不是本项目。

从源码安装

git clone https://github.com/1102tools-dev/federal-contracting-mcps.git
cd federal-contracting-mcps/servers/usaspending-gov-mcp
pip install -e .

配置

将以下配置用作服务定义，并根据你兼容的 MCP 客户端调整其放置位置。要查看使用此来源的实际请求示例，请参阅提示词库。

{
  "mcpServers": {
    "usaspending": {
      "command": "uvx",
      "args": ["--refresh-package", "usaspending-gov-mcp", "--from", "usaspending-gov-mcp", "usaspending-mcp"]
    }
  }
}

--refresh-package 标志会让 uv 在每次客户端启动服务时检查 PyPI 是否有更新版本， 从而自动获取修复；若没有此标志，uv 会一直提供其首次缓存的那个版本。它会在启动时 增加一点网络时间开销，因此如果你的平台对 MCP 启动超时有较短限制，请调高该超时时间。

如果你通过 pip install -e . 或普通 pip install 安装：

{
  "mcpServers": {
    "usaspending": {
      "command": "python",
      "args": ["-m", "usaspending_gov_mcp.server"]
    }
  }
}

重启客户端，工具即可出现。

工具配置集

独立使用默认采用 USASPENDING_TOOL_PROFILE=full，会暴露全部 55 个工具。打包的采购 Agent 会设置 USASPENDING_TOOL_PROFILE=acquisition-agent，以暴露一个稳定的 20 工具子集， 涵盖核心的奖项搜索、支出、机构、受助方、NAICS、PSC、 交易和子奖项操作。未知的配置集会以明确的错误停止启动， 而不是静默更改工具目录。

示例提示词

配置完成后，试试：

• "显示 FY2025 年按金额排名前 10 的 NAVSEA 合同。"
• "查找过去一年 NASA 所有带有单一来源理由的软件开发合同。"
• "自 2020 年以来 Leidos 收到了多少联邦奖项？按财年分组。"
• "DoD 的 HUBZone 预留合同的前 15 大受助方是哪些？"
• "拉取 PIID N00024-24-C-0085 的完整修改历史。"
• "比较 FY2024 空军 IT 服务的 FFP 与 T&M 奖项数量。"

设计说明

• 无需身份验证。 USAspending.gov 是一个免费、公开的 API。
• 财政时间分组。 财年从 10 月持续到 9 月；第 1 季度是 10 月–12 月，第 1 个月是 10 月。new_awards_over_time 将来源的财政季度计数合并为年度财年结果。仅覆盖某一财年部分时间的日期窗口返回的是该请求部分的计数，而不是整年的计数。季度和月度结果保留来源计数。
• FFATA 期间范围。 spending_by_subaward_grouped 对匹配主合同的累计已报告子合同总额进行排名。其日期筛选不会将这些总额裁剪为请求期间内的子合同活动。如需针对特定期间的报告，请将返回的 award_generated_internal_id 传给 search_subawards，读取每一页并按 action_date 筛选记录。已报告金额可能重复累计值；其总和并非净新增分包支出。
• 授予日期窗口。 默认情况下，日期窗口匹配在该期间内处于活动状态的任何授予（从首次签署到最后一次活动），因此匹配并不能证明窗口内发生过某项活动。如需了解实际活动，请使用 spending_by_transaction，读取每一页并对授予标识符去重；get_transactions 给出单个授予的活动日期。显式设置 date_type="action_date" 会限定为最后的活动。
• 联邦账户项目。 项目列表包含所有已报告年份的代码和名称，不含金额，也不按财年筛选。该工具在内部检索来源页面（最多 2,000 条记录），并报告完整性以及任何未应用的请求财年。对于单年账户资源，请将数字账户 ID 与财年快照配合使用。机构项目总计适用于整个机构。
• 可用财年。 账户列表默认使用来源的最新可用财年；请检查 fy，尤其是在 10 月切换之后。如果你请求的年份来源尚不存在，回答会解释哪些年份可用。机构预算资源不提供强制性/可自由裁量拆分。
• 授予类型分组不可混用。 award_type 参数取以下值之一：contracts、idvs、grants、loans、direct_payments、other。不同类别请分别调用。
• program_numbers 仅适用于援助。 将其与设置为 grants、loans、direct_payments 或 other 的 award_type 配合使用。合同和 IDV 没有援助清单，因此服务会返回一条消息，而不是零结果。
• 可操作的错误消息。 常见 API 错误（422 混合授予类型、400 缺少排序字段、400 空关键字）会被转换为给调用方大模型的指导。
• 排序字段自动处理。 USAspending API 要求排序字段出现在 fields 数组中；此服务会自动添加它。
• 合理的默认值。 搜索限制默认为 25（API 最大值为 100）。默认字段涵盖每个授予类别最常见的列。
• 扁平筛选参数。 最常见的筛选器以命名参数形式呈现（keywords、awarding_agency、naics_codes 等），而不是嵌套的筛选字典，以便大模型更好地发现工具。

数据来源

所有数据均来自 USAspending.gov，它汇总了 FPDS-NG 合同数据、FAADC 援助数据以及机构 DATA Act 提交数据。数据新鲜度因机构而异：非 DoD 合同数据通常在 5 个工作日内可用，DoD 和 USACE 采购数据在 FPDS 中有 90 天的报告延迟，而财政援助数据在提交后 2 天内可用。

许可证

MIT

回归测试

在此包目录下运行 PYTHONPATH=src uv run --python 3.12 python -m pytest -q。设置 USASPENDING_LIVE_TESTS=1 可添加针对公共 API 的实时检查（无需密钥）。详情请参阅 testing.md。

测试文件	覆盖范围
test_v0_3_features.py	工具形态、过滤器及扩展的 API 接口
test_density_r5.py	边界与语义回归密度
test_live_audit_r6.py	实时端点审计
test_live_audit_r7.py	实时参数与分页审计
test_content_fixes_1013.py	十月内容修复，离线与实时
test_round_8.py	属性与验证检查
test_entity_family_fixes.py	机构、受助方与奖励语义
test_validation.py	输入验证
test_search_family_fixes.py	搜索与聚合语义
test_response_cache_hosted.py	托管缓存行为
test_audit_r11.py	限速审计锚点
test_throughput.py	请求吞吐量与限速
test_tool_profiles.py	工具配置选择
test_http.py	HTTP 处理
test_content_e2e_1014.py	完整端到端审计指导回归
test_published_scope_1015.py	已发布的工具选择范围指导
test_new_awards_fiscal_year_1016.py	已捕获的年度财年更正及未更改的季度/月度样本
test_subaward_period_scope_1017.py	累积 FFATA 范围及完整带日期报告恢复
test_federal_account_program_scope_1018.py	已捕获的全年度项目范围、完整列表及单年度财务恢复
test_federal_account_available_fy_1020.py	当前财年来源可用性、支持的恢复及未更改的 503 对照
test_naics_current_retired_1021.py	实际已退役行与被请求限制省略的活跃行对比
test_award_date_overlap_r6.py	奖励区间重叠与完整带日期交易恢复对比
test_sdk23_expected_guidance.py	可见的普通恢复提示、无预验证来源请求、保留的来源输出及意外故障屏蔽
总计	2,322