mcp-sam-gov

---

实际效果

👤  user        Find active SAM.gov solicitations under NAICS 541512 closing this month
                                                                                          
🤖  Claude     → sam_search_opportunities { ncode: "541512", limit: 5 }                  
✓  47,478 active opportunities indexed                                                  
                                                                                          
   • 5ef3db5d…  VA Bulk Oxygen Tank Rental         closes 2026-05-15  ($1.05M)         
   • a000339c…  Articulating Boom Lifts             closes 2026-05-30  ($310K)          
   • be9c24ef…  CMOP Hazardous Waste Removal        closes 2026-06-12  ($2.7M)          

👤  user        Pull the SOW + contracting officer for the first one
                                                                                          
🤖  Claude     → sam_get_opportunity { noticeId: "5ef3db5d…" }                          
✓  Department of Veterans Affairs · Combined Synopsis/Solicitation                       
   POC:           Contracting Officer  <[email protected]>  +1-XXX-XXX-XXXX             
   Set-aside:     Total Small Business                                                    
   Attachments:   1   ↓ 36C24526Q0460_1.docx (172 KB)                                     
   SOW preview:   "RFQ# 36C24526Q0460 — Bulk Oxygen Tank Rental, Fill, Telemetry…"        

153 个工具中有 148 个无需 API 密钥、注册或报名。 接入后直接提问即可。

---

为什么要做这个项目

现状	使用此 MCP 后
GovWin：每个席位每年 3 万至 10 万美元	免费，采用 MIT 许可证
注册 API 密钥 → 等待 24 小时 → 挑选配额套餐	npm install → 60 秒内即可使用
5 个以上独立的供应商 API／抓取工具	统一接口，54 个数据源提供 153 个工具
大模型会幻觉出 NAICS 代码／机构名称	内置防幻觉自动补全保护
脆弱的抓取每周都会失效	每日实时冒烟测试（上方徽章）
采购专员 → IT 工单 → 等待 3 周	双击即可安装到 Claude Desktop

此项目封装的联邦数据属于公有领域。查询这些数据没有任何合理理由需要支付五位数的订阅费。

---

Claude（及其他 AI Agent）可以借助它做什么

领域	可以询问什么	数据来源
🔍 商机与招标公告	“查找 NAICS 541512 下本月截止的 SAM.gov 招标公告”——阅读工作说明书（SOW）、联系人（POC）和附件	SAM.gov、Grants.gov
💰 支出、奖项与竞争情况	“显示 Booz Allen 上一财年在 VA 获得的合同；DoD 排名前 10 的 PSC 类别”	USAspending、FPDS、GAO
🕵️ 实体与合作伙伴审查	“审查这家公司：OFAC 制裁、SAM 排除名单、单一审计结果、银行健康状况、EPA 合规情况及有毒物质排放”	OFAC、SAM、FAC、FDIC、EPA ECHO、EPA Envirofacts
🛒 产品安全与召回	“FDA/NHTSA/CPSC 是否对这家供应商的产品发布过召回或采取过执法行动？”	openFDA、NHTSA、CPSC
⚖️ 诉讼与法院	“有没有涉及这家承包商的联邦索赔法院投标抗议或联邦巡回上诉法院意见？”	CourtListener（Free Law Project）
🏢 非营利供应商	“在与这家非营利机构分包前，调取它的 IRS-990 财务数据”	IRS 990（通过 ProPublica）
🏥 医疗服务提供者与机构	“该医疗服务提供者的 Medicare 使用量和付款情况；医院质量评级；该提供者是否在撤销名单上？”	CMS（data.cms.gov）
📈 财务披露（SEC）	“调取这家上市公司的营收趋势和最新 10-K 文件”	SEC EDGAR
⚖️ 监管与立法	“本季度发布了哪些 VA 网络安全规定？Regulations.gov 上有没有尚未结案的案卷？”	Federal Register、Regulations.gov、eCFR、FAR/DFARS、Congress.gov、GovInfo
💲 定价、劳动力与财政	“系统分析师的 GSA CALC 薪资范围；该县的 SCA 工资决定；CPI 调整；出差每日津贴上限；按行业划分的地区 GDP；DOL 工资与工时执法历史”	GSA CALC、SAM WDs、BLS、US Census CBP、FRED、BEA、US Treasury、GSA per-diem、US DOL
🏛 游说与影响力	“谁在就网络安全问题游说 VA？他们花了多少钱？”	US Senate LDA
🏥 卫生与研究资助	“该主题的 NIH/NSF 资助项目；正在招募受试者的临床试验；向这位医生支付款项的行业”	NIH RePORTER、NSF、ClinicalTrials.gov、CMS Open Payments、NPPES
🛡 网络安全合规	“这项 CVE 是否在 CISA KEV 必须修补名单上？”	NVD、CISA KEV
🌐 贸易、地理与灾害	“该产品的 HTS 关税；该地址所属的人口普查区；该州的 FEMA 灾害声明”	USITC HTS、US Census、FEMA、Socrata、CKAN
🏙 州/地方采购投标（SLED）	“这座城市/县的采购门户目前有哪些开放项目？查看其支票簿、已授予合同、供应商付款；州 DOT 投标/授标登记册”	OpenGov Procurement（525+ 个政府机构）、Bonfire、ArcGIS（feature + Hub）、Socrata（54 个主机）、一个 Tableau Server Guest 视图（Montana）、一个 Socrata Open Expenditures 支票簿（South Dakota）
🎓 资助与数据集	“查找过去 30 天发布的网络安全资助；发现联邦开放数据集”	Grants.gov、data.gov

153 个工具，覆盖 54 个数据源——优先免密钥：仅 4 个来源（Census business-patterns、FRED、BEA 和 DOL 的数据端点）需要免费密钥，其余 50 个均无需密钥。（早期的 52 工具版本在生产环境的联邦 API 上测得约 p50 ~0.25s / p95 ~0.8s；延迟因数据源和上游负载而异——可视为快速响应，但不代表经基准测试保证的性能。）

---

如何安装？选择适合你的方式。

🟢 方式 1 — Claude Desktop，一键安装（无需终端）

最适合非开发者。只需下载一个文件并双击。

1. 从最新发布版本下载 mcp-sam-gov.mcpb。
2. 双击该文件。Claude Desktop 将打开“安装扩展”对话框。
3. 点击 安装。
4. 完成。开始新对话，并询问“查找 NAICS 541512 下正在生效的 SAM.gov 商机”。

就这么简单。无需 PowerShell、无需 npm，什么都不需要。

需要 Claude Desktop ≥ 1.0（该版本自带 Node.js 运行时）。

🟡 路径 2 — Claude Code，一条命令

如果你已经在使用 Claude Code（CLI）：

/plugin install cliwant/mcp-sam-gov

这会安装 MCP 服务，并且安装一个 SKILL.md 工作流指南，教 Claude 何时以及如何使用这 153 个工具中的每一个。

🔵 路径 3 — 为任何 MCP 宿主手动安装（Codex、Cursor、Continue、Gemini）

适用于 Codex CLI / Cursor / Continue / Gemini CLI / 任何支持 MCP 的工具：

gh repo clone cliwant/mcp-sam-gov
cd mcp-sam-gov
npm install --omit=dev
npm install -g .

安装完成后，二进制文件 mcp-sam-gov 就会位于你的 PATH 中。将以下内容添加到宿主配置中：

{
  "mcpServers": {
    "sam-gov": {
      "command": "mcp-sam-gov"
    }
  }
}

各宿主对应的具体配置位置：请参见下文的宿主配置。

不想全局安装？ 以下每种宿主配置也提供 npx 版本（npx -y @cliwant/mcp-sam-gov），无需克隆仓库，也无需运行 npm install -g。只需要 Node.js。

⚪ 路径 4 — 直接指定路径（零安装，只需指向文件）

完全跳过安装：

gh repo clone cliwant/mcp-sam-gov
cd mcp-sam-gov
npm install --omit=dev   # only runtime deps; dist/ is pre-built

然后在宿主配置中指定绝对路径：

{
  "mcpServers": {
    "sam-gov": {
      "command": "node",
      "args": ["C:\\Users\\you\\mcp-sam-gov\\dist\\server.js"]
    }
  }
}

---

宿主配置

以下每种宿主都展示了两种配置方式，任选其一：

• 全局安装："command": "mcp-sam-gov"。只有在运行 npm install -g（路径 3）并将 mcp-sam-gov 二进制文件添加到 PATH 后，此方式才有效。
• 不全局安装（npx）："command": "npx", "args": ["-y", "@cliwant/mcp-sam-gov"]。只需要 Node.js。npx 首次运行时会从 npm 下载软件包并将其缓存。

软件包名称： npm 软件包使用作用域：@cliwant/mcp-sam-gov。mcp-sam-gov 只是全局安装后添加到 PATH 中的二进制文件名称。npm 上不存在未指定作用域的 mcp-sam-gov 软件包，因此 npx -y mcp-sam-gov 会因 404 而失败。请使用 npx -y @cliwant/mcp-sam-gov。

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

全局安装：

{
  "mcpServers": {
    "sam-gov": { "command": "mcp-sam-gov" }
  }
}

不全局安装（npx）：

{
  "mcpServers": {
    "sam-gov": { "command": "npx", "args": ["-y", "@cliwant/mcp-sam-gov"] }
  }
}

在 Windows 上，如果服务在 %APPDATA%\Claude\logs\mcp*.log 中报错 spawn npx ENOENT，请用 cmd /c 包装 npx：

{
  "mcpServers": {
    "sam-gov": { "command": "cmd", "args": ["/c", "npx", "-y", "@cliwant/mcp-sam-gov"] }
  }
}

（也可以完全跳过这些步骤——使用路径 1 的 .mcpb，它会自动配置。）

完全重启 Claude Desktop（Windows 上从系统托盘退出 / macOS 上从菜单中选择“退出”），然后查找 🔨 图标。你应该会看到“sam-gov（153 个工具）”。

Claude Code

项目级 .mcp.json，全局安装：

{ "mcpServers": { "sam-gov": { "command": "mcp-sam-gov" } } }

不全局安装（npx）：

{ "mcpServers": { "sam-gov": { "command": "npx", "args": ["-y", "@cliwant/mcp-sam-gov"] } } }

或者使用 CLI：

# global install
claude mcp add sam-gov mcp-sam-gov

# no global install (npx)
claude mcp add sam-gov -- npx -y @cliwant/mcp-sam-gov

Codex CLI

~/.codex/config.toml：

全局安装：

[mcp_servers.sam-gov]
command = "mcp-sam-gov"
args = []

不全局安装（npx）：

[mcp_servers.sam-gov]
command = "npx"
args = ["-y", "@cliwant/mcp-sam-gov"]

Cursor

设置 → MCP → 添加新的 MCP 服务。全局安装：

{ "mcpServers": { "sam-gov": { "command": "mcp-sam-gov" } } }

不全局安装（npx）：

{ "mcpServers": { "sam-gov": { "command": "npx", "args": ["-y", "@cliwant/mcp-sam-gov"] } } }

Continue

~/.continue/config.json，全局安装：

{
  "experimental": {
    "modelContextProtocolServer": {
      "transport": { "type": "stdio", "command": "mcp-sam-gov" }
    }
  }
}

不全局安装（npx）：

{
  "experimental": {
    "modelContextProtocolServer": {
      "transport": { "type": "stdio", "command": "npx", "args": ["-y", "@cliwant/mcp-sam-gov"] }
    }
  }
}

Gemini CLI

~/.gemini/settings.json，全局安装：

{ "mcpServers": { "sam-gov": { "command": "mcp-sam-gov" } } }

不全局安装（npx）：

{ "mcpServers": { "sam-gov": { "command": "npx", "args": ["-y", "@cliwant/mcp-sam-gov"] } } }

VS Code

在项目根目录下添加 .vscode/mcp.json（VS Code 使用 "servers"，而不是 "mcpServers"）：

{
  "servers": {
    "sam-gov": {
      "command": "npx",
      "args": ["-y", "@cliwant/mcp-sam-gov"]
    }
  }
}

或者使用本页面顶部的一键徽章，直接从浏览器安装。

Kiro

使用本页面顶部的一键徽章添加服务。Kiro 会打开一个已填入 npx 命令的安装对话框。

其他工具

如果你的宿主通过 stdio 支持 MCP，请将其指向 mcp-sam-gov（全局安装）或 npx -y @cliwant/mcp-sam-gov（不全局安装）。无需编写宿主专用代码。

---

可以问哪些问题？

安装完成后，你可以用自然语言提问。Agent 会自动选择合适的工具调用顺序。

发现

• “NAICS 541512 의 메릴랜드 입찰 중 30일 안에 마감되는 것 찾아줘”
• “查找 NAICS 541512 下有效的 SAM.gov 招标，仅限 MD，且在 30 天内截止”
• “‘computer systems design’ 的标准 NAICS 代码是什么？”

RFP 分析

• “提取 noticeId 5ef3db5daeb54099a96d487783a38bd0——提供 SOW、合同官员和附件”
• “显示该公告的完整 RFP 正文”

竞争格局

• “上一财年 NAICS 541519 中获得 VA 合同最多的 5 家机构”
• “显示 Booz Allen 在 DISA 获得的各项奖励”
• “Leidos 的 VA 合同有哪些分包商？”
• “USAspending 中的 CMS 是什么？（解析该缩写）”

趋势与汇总

• “过去 5 个财政年度，VA 在 541512 领域的支出趋势如何？”
• “按联邦合同支出排名的 541512 前 10 个州”
• “DoD 支出最高的 PSC 类别”
• “按总金额统计的网络安全联邦拨款项目”

机构情报（投标简报）

• “为 VA 提供一份投标简报：使命、FY26 预算明细、主要下属机构”
• “VA 在 FY25 的交易量是多少？”

合同续签预警

• “未来 12 个月内到期且金额超过 $1M 的 VA 541512 合同”
• “查找奖励 CONT_AWD_... 的履约期限”

监管与立法

• “查找关于 SDVOSB 保留合同要求的 FAR 条款”
• “将这份 RFP 引用的 FAR/DFARS 条款列表整理成 Section L/M 合规矩阵”
• “本季度发布了哪些新的 VA 网络安全规定？”
• “今天 DoD 有文件在 Federal Register 公示查阅台上吗？”
• “搜索 Regulations.gov 上有关 ‘contractor cybersecurity’ 的案卷，并提取公众意见”
• “在 data.gov 上查找关于 ‘wildfire’ 的联邦开放数据集”
• “是否有编号为 2026-08333 的 Federal Register 文件？提取引文。”

合作伙伴与实体审查

• “根据 OFAC 制裁名单和 SAM 排除名单审查 ‘Acme Defense LLC’”
• “在 NPPES 中查询 NPI 1234567890——该服务提供方是否处于有效状态？”
• “这家分包商在 Federal Audit Clearinghouse 中是否有不利的 Single Audit 结果？”
• “证书编号 #3510 对应的银行财务状况如何——风险比率和季度财务数据是什么？”
• “提取这家上市公司的营收趋势，以及 SEC EDGAR 上最新的 10-K”
• “该设施是否有 EPA 合规或执法方面的风险标记？”

合规与资格

• “NAICS 541512 的 SBA 小型企业规模标准是什么？”
• “在 eCFR 中搜索某项规则的准确文本”
• “锂离子电池的美国进口关税税率（HTS）是多少？”

定价、劳动力与财政

• “资深系统分析师在 GSA CALC 上的最高费率区间”
• “查找马里兰州巴尔的摩县的 SCA 工资裁定，并提供附加福利费率”
• “过去 3 年 CPI-U 上涨了多少，可用于升级条款？”
• “美国当前公共债务总额是多少（Debt to the Penny）？”

网络安全

• “CVE-2021-44228（Log4Shell）是否在 CISA KEV 必须修补清单中？截止日期是什么时候？”

医疗与研究经费

• “NIH RePORTER 中去年获得资助的 mRNA 疫苗项目”
• “由行业赞助、正在招募糖尿病患者的临床试验”
• “CMS Open Payments Research 数据集中加州支付给医生的行业款项”

拨款

• “过去 30 天发布的网络安全拨款”
• “提取拨款 ID 361238”

---

可选 — 更高的速率限制与历史档案

MCP 服务默认无需密钥。如需提高 SAM.gov 速率限制并访问完整档案（约 12 个月以前的公告），请在主机的 env 块中设置 SAM_GOV_API_KEY：

{
  "mcpServers": {
    "sam-gov": {
      "command": "mcp-sam-gov",
      "env": { "SAM_GOV_API_KEY": "your-key-here" }
    }
  }
}

可在 sam.gov/SAM/pages/public/searchKeyData.jsf 免费获取密钥。Agent 无需知道密钥——密钥路径会透明处理。

DATA_GOV_API_KEY — api.data.gov / api.gsa.gov 系列

少数数据源通过共享的 api.data.gov 网关提供服务，包括 Congress.gov、GovInfo、Regulations.gov、FAC、GSA 每日津贴，以及 data.gov v4 数据集目录。它们默认通过公开的 DEMO_KEY 无需密钥即可使用（共享的每小时配额较低）。设置 DATA_GOV_API_KEY 可大幅提高这些限制：

{
  "mcpServers": {
    "sam-gov": {
      "command": "mcp-sam-gov",
      "env": { "DATA_GOV_API_KEY": "your-key-here" }
    }
  }
}

可在 api.data.gov/signup 免费获取（即时获取，无需等待）。同一个密钥可用于所有 api.data.gov / api.gsa.gov 数据源。与 SAM 密钥一样，密钥只会在网络传输时发送（绝不会记录日志）；未设置时会使用 DEMO_KEY。BLS 数据源同样支持可选的免费 BLS_API_KEY，用于提高每日配额。

密钥与更高限额 — 完整清单

大多数工具无需密钥。 四个数据源需要免费密钥 — Census（census_business_patterns）、FRED（fred_search_series、fred_series_observations）、BEA（bea_regional_data）和 DOL 的数据端点（dol_get_dataset）— 这些数据源没有免密档位，因此未提供密钥时工具会报错。（DOL 的目录 dol_list_datasets 无需密钥。）其他密钥都是可选的：它们只会提高速率限制或解锁单个筛选条件。以下所有密钥均免费。

环境变量	是否必需？	解锁内容	免费注册
CENSUS_API_KEY	必需	census_business_patterns（没有免密档位 — 未提供密钥时会报错）	api.census.gov/data/key_signup.html
FRED_API_KEY	必需	2 个 FRED 工具（没有免密档位 — 未提供密钥时会报错）	fred.stlouisfed.org/docs/api/api_key.html
BEA_API_KEY	必需	bea_regional_data（BEA Regional；没有免密档位 — 未提供密钥时会报错）	apps.bea.gov/API/signup
DOL_API_KEY	获取数据时必需	dol_get_dataset（通过 X-API-KEY 获取 DOL 执法记录；dol_list_datasets 目录无需密钥）	dol.gov/developer
DATA_GOV_API_KEY	可选	提高所有 api.data.gov 数据源的限额（Regulations.gov、Congress.gov、GovInfo、FAC、data.gov 目录、GSA 每日津贴）— 提高共享的 DEMO_KEY 限额	api.data.gov/signup
SAM_GOV_API_KEY	可选	通过身份验证的 SAM.gov v2 搜索，以及机构名称筛选条件	open.gsa.gov/api/get-opportunities-public-api
LDA_API_KEY	可选	提高 lda_search_filings 的速率限制（参议院 LDA 游说数据；默认无需密钥）	lda.senate.gov/api/register
BLS_API_KEY	可选	BLS v2 档位（每天约 500 次查询，免密约 25 次）	data.bls.gov/registrationEngine
NVD_API_KEY	可选	提高 NVD 速率限制（cve_lookup）	nvd.nist.gov/developers/request-an-api-key
OPENFDA_API_KEY	可选	提高 openFDA 速率限制（openfda_enforcement、openfda_device_clearances；两者均可免密使用）	open.fda.gov/apis/authentication
COURTLISTENER_API_TOKEN	可选	提高 CourtListener 速率限制（courtlistener_search_opinions；可免密使用）	courtlistener.com/help/api/rest
SOCRATA_APP_TOKEN	可选	提高 Socrata 限流阈值	evergreen.data.socrata.com/signup

设置任意密钥有两种方式 — 任选其一：

1. 宿主环境变量区块 — 上方示例中显示的 "env": { … } 对象。
2. 在服务工作目录中创建 .env 文件 — 一次性配置密钥：

   CENSUS_API_KEY=your-key-here
   FRED_API_KEY=your-key-here
   # optional — raise limits / unlock filters
   SAM_GOV_API_KEY=your-key-here
   

   服务启动时会自动加载 .env。真实环境变量的优先级始终高于 .env（标准优先级规则），且 .env 已被 git 忽略，因此密钥不会被提交。

询问服务需要哪些密钥。 无需密钥的 api_key_status 工具会列出所有密钥、它们是必需还是可选、免费注册 URL 和解锁内容，以及每个密钥当前是否已配置（布尔值 — 不会显示密钥值）。你只需手动在注册 URL 创建账户；服务会自动完成发现（api_key_status）和配置（.env）。如需确认密钥确实有效，请调用对应数据源自己的工具。

---

选择工具集（缩小上下文）

默认情况下会加载全部 153 个工具 — 每个会话约占用 74k 个令牌。需要承担完整上下文开销的客户端（Claude Desktop、Cursor、原始 API）可以只加载与任务相关的工具集，大幅减少开销。

将 MCP_SAM_GOV_TOOLSETS 环境变量设为以逗号分隔的工具集名称列表（不区分大小写）。留空（或设为 all）即可恢复加载全部工具。

令牌数量为近似值，计算方式是将每个 tools/list 条目的精简 JSON 字符数除以 4。 feedback 和 api_key_status 在所有配置中始终加载（无论启用哪个工具集，它们都能帮助 Agent 报告问题和检查密钥状态）。

工具集	工具数	近似令牌数	涵盖内容
core	60	~17k	SAM.gov 发现/附件/工资标准判定/排除名单/诚信；Grants.gov；全部 USAspending；FPDS；GAO；FAR/eCFR/Federal Register；SBA；OFAC 筛查；GSA 劳动力费率基准；api_key_status；feedback（始终加载）
sled	13	~7k	州/地方（SLED）采购：OpenGov、Bonfire、ArcGIS、Socrata、data.gov/CKAN、Tableau、Open Checkbook、search.gov 域名
vetting	17	~10k	合作伙伴尽职调查：FAC、FDIC、EPA ECHO/TRI、CourtListener、非营利组织（IRS 990）、参议院 LDA 游说
disclosure	8	~5k	SEC EDGAR 财务申报和 XBRL 数据框架
regulatory	9	~4k	Regulations.gov、Congress.gov、GovInfo
pricing	15	~9k	GSA 差旅津贴、BLS、Treasury、BEA、Census 商业模式数据、FRED、DOL、USITC HTS
health	17	~12k	CMS、NPPES、NIH、NSF、ClinicalTrials.gov、openFDA
safety	3	~2k	NHTSA 车辆召回、CPSC 消费品召回
geo	8	~5k	Census 地理编码、FEMA 灾害、NWS 警报、CBP 边境等待时间、data.gov 目录
cyber	3	~2k	NVD CVE、CISA KEV、NIST SP 800-53
all	153	~74k	全部工具（默认）

配置示例：

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "sam-gov": {
      "command": "npx",
      "args": ["-y", "@cliwant/mcp-sam-gov"],
      "env": { "MCP_SAM_GOV_TOOLSETS": "core,sled" }
    }
  }
}

Claude Code（命令行）：

claude mcp add sam-gov -e MCP_SAM_GOV_TOOLSETS=core,sled -- npx -y @cliwant/mcp-sam-gov

Claude Desktop bundle（.mcpb / manifest user_config）：在扩展设置对话框中设置 Toolsets 字段（留空 = 全部）。

如果你调用的工具属于未加载的工具集，服务会返回结构化的 tool_not_loaded 错误，其中会指出工具集名称以及需要设置的确切环境变量。建议值为当前已加载工具集与所需工具集的并集（例如，已加载 core 并调用 vetting 工具时，设为 MCP_SAM_GOV_TOOLSETS=core,vetting），以免静默丢弃现有配置。服务绝不会静默返回空结果。

---

保持最新

npm 不会通知已安装的用户有新版本，因此服务会以尽可能精简的方式进行提示。启动时，它会向公共 npm 注册表发起一次匿名请求，检查自身的最新版本，并且仅在发现有更新版本时，向 stderr 输出一行提示（例如 a newer version is available: 1.7.0 → 1.8.0）。它不会发送使用数据（这是版本检查，而非遥测），绝不会访问该协议的 stdout；检查不会阻塞启动，当前版本为最新时也不会显示任何提示。

• 更新： npm i -g @cliwant/mcp-sam-gov@latest — 或者，如果配置使用 npx @cliwant/mcp-sam-gov@latest，只需重启即可。
• 退出检查： 将 MCP_SAM_GOV_NO_UPDATE_CHECK=1（或 NO_UPDATE_NOTIFIER=1）设为环境变量。
• 变更内容： releases page + CHANGELOG。

发现了 Bug？想要新功能？一步即可反馈

此服务旨在根据实际使用情况持续改进。由于调用工具的是 AI Agent（而非人类），反馈流程会通过 Agent 进行：

• 遇到两种“可能出问题了”的错误时——schema_drift（联邦 API 的结构发生了变化）和 upstream_unavailable（服务中断）——错误信息中会包含 report 字段：一个预先填好的 GitHub issue 链接，Agent 可以提供给你。
• 或者直接告诉你的 Agent“报告 Bug”／“这个结果看起来不对”／“希望它能做到 X”——它会调用 feedback 工具，返回一个预先填好的 issue 链接，供你打开并提交。

不会自动发布任何内容。 服务没有令牌，也没有账户——它只会生成链接；由你打开并提交。预先填好的链接只包含工具名称、错误类型和服务版本，绝不会包含你的查询值。代码仓库是公开的，请先删除任何敏感信息。

你也可以直接打开：新建 issue — Bug／功能／输出错误模板。

工具目录（153 个工具）

按工作流分组。优先免密——大多数工具无需密钥；Census business-patterns、FRED、BEA 和 DOL 的数据端点需要免费密钥，另外少数工具使用可选免费密钥可获得更高限额（详见上文说明）。描述经过精简——每个工具自己的 inputSchema 都包含完整约定和有关限制的说明。

机会与招标 — SAM.gov + Grants.gov（10 个工具）

• sam_search_opportunities — 免密搜索 SAM.gov 当前有效的联邦合同机会
• sam_search_shaping — 招标前雷达（RFP 发布前的 Sources Sought / Presol / Special Notices）
• sam_get_opportunity — 根据 32 位十六进制 noticeId 获取完整详情（联系人 + 附件 + 正文）
• sam_fetch_description — 获取纯文本格式的完整 RFP 正文
• sam_fetch_attachment_text — 从 PDF + DOCX + 文本/HTML 中提取附件文本（RFP / SOW / 问答 / 工资表）
• sam_attachment_url — 根据附件 resourceId 生成公开下载 URL
• sam_lookup_organization — 将联邦机构 ID 转换为规范的 fullParentPathName
• sam_lookup_notice_fields — 从 GSA 每日 CSV 批量填充 1–100 个 noticeId 中为空的 naics/set-aside/PoP/deadline 字段（需主动选择加入）
• grants_search — Grants.gov 联邦拨款机会（财政援助，与 SAM 合同不同）
• grants_get_opportunity — 根据 id 获取单项拨款机会的完整详情

支出、奖项与竞争 — USAspending + FPDS + GAO（31 个工具）

- `usas_search_awards` — 按机构 × NAICS 汇总钱包份额 - `usas_search_individual_awards` — 联邦合同明细（返回 generatedInternalId） - `usas_get_award_detail` — 完整授标详情：履约期、选项、预留类别、竞争情况 - `usas_search_awards_by_recipient` — 某个接收方在机构 × NAICS 范围内赢得的所有合同 - `usas_search_subawards` — 列举主要授标下的分包合同（供应链 / 组队） - `usas_search_recompetes` — 重新竞标监测（履约期在指定时间范围内结束，按时间先后排序，不静默丢弃结果） - `usas_search_expiring_contracts` — **已弃用**，`usas_search_recompetes` 的别名（旧版格式） - `usas_analyze_incumbent` — 按授标列出在任承包商 + 公开的重新竞标压力提示（标签，而非评分） - `usas_search_teaming_partners` — 按认证类别 × NAICS × 机构发现小企业组队伙伴，并筛除受限对象 - `usas_spending_over_time` — 合同支出时间序列（财年 / 季度 / 月） - `usas_search_agency_spending` — 按授标机构细分支出 - `usas_search_subagency_spending` — 将上级机构支出细分到下属机构 / 办公室 - `usas_search_psc_spending` — 按产品服务代码（PSC）统计支出 - `usas_search_cfda_spending` — 按 CFDA 补助项目代码统计支出 - `usas_search_state_spending` — 按州 / 地区统计支出 - `usas_search_federal_account_spending` — 按联邦账户 / 财政部账户符号（TAS）统计支出 - `usas_search_recipients` — 接收方列表，包含母子级层级关系 - `usas_get_recipient_profile` — 接收方完整详情（UEI、别名、总额） - `usas_get_agency_profile` — 按 toptier 代码查询机构档案（使命、缩写、网站） - `usas_get_agency_awards_summary` — 某财年的授标活动（交易数量 + 承诺金额） - `usas_get_agency_budget_function` — 按机构 × 财年细分预算职能 - `usas_list_toptier_agencies` — 所有 toptier 机构 + 当前财年的承诺金额 - `usas_lookup_agency` — 将“VA” / “DHS”解析为规范的 toptier 名称 + 4 位代码 - `usas_autocomplete_naics` — 防止幻觉的 NAICS 校验工具 - `usas_autocomplete_recipient` — 防止幻觉的接收方校验工具 - `usas_naics_hierarchy` — 浏览 NAICS 树（2→4→6）+ 每个代码对应的有效合同数量 - `usas_glossary` — 151 个联邦支出术语 - `usas_list_disaster_codes` — 列出灾害应急基金代码（DEFC）：COVID-19、IIJA / 基础设施及其他紧急拨款标签 - `usas_disaster_spending` — 按地理区域查询指定 DEFC 的灾害 / 应急基金支出（哪些州 / 县 / 选区获得了 COVID / IIJA 救济资金） - `fpds_search_awards` — FPDS-NG 联邦合同授标操作（权威授标操作数据源） - `gao_protest_lookup` — 通过公开 Legal-Products RSS 源查询近期 GAO 投标抗议裁决（仅限近期时间范围）

实体与合作伙伴审查 — OFAC · SAM · FAC · FDIC · EPA（15 个工具）

- `ofac_screen_entity` — 无需密钥的 OFAC 禁止交易方／制裁筛查 - `sam_check_exclusions` — 无需密钥，按名称和／或 UEI/CAGE 进行 SAM 禁止交易／排除筛查 - `sam_integrity_lookup` — 一站式诚信筛查（排除判定 + 如实提供 FAPIIS 入口） - `fac_search_audits` — 从 Federal Audit Clearinghouse 获取单次审计摘要 - `fac_get_findings` — 深入查看某实体的审计风险发现 - `fdic_search_institutions` — 搜索 FDIC 保险机构目录 - `fdic_institution_financials` — 单家机构的季度财务时间序列（按 cert # 查询） - `fdic_risk_ratios` — 单家机构的交易对手风险比率 - `fdic_institution_history` — 结构变更事件日志（合并、牌照变更） - `fdic_branch_deposits` — 分行存款分布 - `fdic_bank_failures` — 历史银行倒闭和援助交易 - `fdic_industry_summary` — 行业及各州银行业年度汇总数据 - `echo_search_facilities` — 按州搜索受 EPA 监管的设施，并筛查合规与执法情况 - `echo_facility_report` — 单个设施的 EPA ECHO 详细设施报告（按 FRS RegistryID 查询） - `epa_tri_facilities` — 按州／行业查询 EPA Envirofacts TRI（有毒物质排放清单）设施（用于环境／ESG 审查）

产品安全与召回 — openFDA · NHTSA · CPSC（6 个工具）

• openfda_enforcement — FDA 药品／器械／食品召回及执法行动（用于产品安全供应商审查）
• openfda_device_clearances — FDA 510(k) 医疗器械许可（用于评估器械制造商能力）
• openfda_drug_approvals — openFDA Drugs@FDA 药品审批申请（申办方、获批产品、提交／审批历史）
• nhtsa_recalls — 按品牌／型号／年份查询 NHTSA 车辆召回
• nhtsa_complaints — 按品牌／型号／年份查询 NHTSA 车辆安全投诉
• cpsc_recalls — CPSC 消费品召回（用于产品供应商审查）

诉讼与法院 — CourtListener（2 个工具）

• courtlistener_search_opinions — 美国联邦法院意见书（COFC 合同索赔／投标抗议、联邦巡回上诉法院）；party 参数用于查询实际当事人相关案件 — 数据来自 CourtListener / Free Law Project（已披露）
• courtlistener_search_dockets — FCA／《虚假索赔法》／qui tam 事项的 RECAP 案件日程（type=r），这类案件很少产生意见书；可按 suitNature 字段筛选 — 数据来自 CourtListener / Free Law Project（已披露）

非营利组织供应商 — 通过 ProPublica 查询 IRS 990（2 个工具）

• nonprofit_search — 按名称／州／NTEE 搜索 IRS 990 非营利组织 — 通过 ProPublica Nonprofit Explorer（已披露）
• nonprofit_financials — 按 EIN 查询 IRS 990 非营利组织财务数据 — 通过 ProPublica Nonprofit Explorer（已披露）

财务披露 — SEC EDGAR（8 个工具）

• edgar_lookup_cik — 将公司股票代码或名称解析为 10 位 SEC CIK
• edgar_company_filings — 某公司的 SEC 文件
• edgar_company_facts — 为申报者整理的 XBRL 财务事实
• edgar_company_concept — 单个申报者 × 单个 XBRL 概念 × 完整报告时间序列
• edgar_xbrl_frames — 跨申报者 XBRL 横截面数据（某一时期内所有申报者的单个概念）
• edgar_full_text_search — 对 EDGAR 文件进行全文搜索，范围为 2001 年至今
• edgar_filing_index — 按季度查询跨申报者批量文件索引
• edgar_daily_filing_index — 按日查询跨申报者文件索引

监管与立法 — Federal Register · Regulations.gov · eCFR · FAR · Congress · GovInfo（19 个工具）

- `fed_register_search_documents` — 按查询词 / 机构 / 类型 / 日期搜索《联邦公报》文件 - `fed_register_get_document` — 按编号获取文件完整详情（引文、正文 URL、CFR 引用） - `fed_register_public_inspection` — 《联邦公报》公众查阅台（正式发布前） - `fed_register_list_agencies` — 《联邦公报》机构名称缩写参考 - `regulations_search_dockets` — 搜索 Regulations.gov 规则制定案卷 - `regulations_search_documents` — 搜索 Regulations.gov 规则制定文件（规则、拟议规则、通知） - `regulations_search_comments` — 搜索针对规则制定的公众意见 - `regulations_get_docket` — 按 ID 获取一份 Regulations.gov 案卷 - `ecfr_search` — 在整个 CFR 中进行全文搜索（FAR 使用 `titleNumber=48`）；返回排名后的摘要片段和 ecfrUrl - `ecfr_get_section` — 按引文获取一个 CFR 条款的完整文本（适用于任何标题；查询 FAR/DFARS 时优先使用 `far_clause_lookup`） - `ecfr_list_titles` — 全部 50 个 CFR 标题及其最近修订日期 - `far_clause_lookup` — 权威 FAR/DFARS 条款文本及其适用规定（精确条款编号） - `far_search` — 在 FAR/DFARS 范围内搜索（排除 GSAM，合并为当前生效版本） - `far_compliance_matrix` — 将引用条款列表转换为适用于提案的 L/M 部分合规矩阵（标记资格门槛） - `congress_search_bills` — 搜索 Congress.gov 法案 / 立法 - `congress_get_bill` — 按国会 / 类型 / 编号获取一项法案 - `govinfo_search_packages` — 在某个集合中搜索 GovInfo（GPO 权威来源）数据包 - `govinfo_get_package` — 获取一个 GovInfo 数据包摘要及下载链接（txt/xml/pdf/mods） - `govinfo_list_collections` — GovInfo 集合目录

定价、劳动力与财政 — GSA CALC · SAM WDs · BLS · Census CBP · FRED · BEA · US Treasury · GSA per-diem（15 个工具）

• gsa_benchmark_labor_rates — 获取某劳动力类别的 GSA CALC 已授标最高费率市场区间（一个分布，而非单一价格）
• sam_search_wage_determinations — 查找某地区的 SCA / Davis-Bacon 工资裁定
• sam_get_wage_rates — 从工资裁定中解析出的现行工资 + 福利 / 健康与福利费率表，以及 EO 最低工资下限
• bls_timeseries — BLS 时间序列（CPI-U / ECI 调整、PPI、就业）— 定价 / 调整层
• bls_oews_wages — 按地区 × 职业划分的职业工资与就业基准（BLS OEWS）
• bls_qcew — 按县 × NAICS 划分的市场规模 / 工资 / 区位商（竞争密度）
• treasury_debt_to_penny — 每日美国公共债务未偿总额（Treasury Fiscal Data）
• treasury_avg_interest_rates — 财政部按证券类型支付的平均利率
• treasury_monthly_statement — 月度财政部报表：按月列出的收入、支出、赤字 / 盈余
• treasury_query_dataset — 对 7 个已确认 Treasury Fiscal Data 数据集进行的备用查询
• bea_regional_data — 按行业 × 地理区域划分的 GDP / 个人收入（BEA Regional；需要免费的 BEA_API_KEY）
• census_business_patterns — 按 NAICS × 地理区域划分的机构 / 就业 / 年度工资总额（Census CBP；需要免费的 CENSUS_API_KEY）
• fred_search_series — 搜索 FRED 宏观经济时间序列目录（GDP/CPI/利率/失业率；需要免费的 FRED_API_KEY）
• fred_series_observations — 获取 FRED 时间序列的数据观测值（缺失值 → null；需要免费的 FRED_API_KEY）
• gsa_perdiem_rates — 联邦差旅每日津贴：按城市 + 州或邮编查询每月住宿及 M&IE 餐费上限（通过 DEMO_KEY 无需密钥）

健康与研究经费 — NIH · NSF · ClinicalTrials · CMS · NPPES（9 个工具）

- `nih_reporter_search_projects` — 已获 NIH RePORTER 资助的研究项目 - `nsf_search_awards` — 已获 NSF 资助的研究项目 - `nsf_get_award` — 按数字奖项 ID 查询单个 NSF 奖项 - `clinicaltrials_search_studies` — 联邦注册的临床研究，含赞助方／资助方补充信息 - `clinicaltrials_get_study` — 按 NCT ID 查询单项临床研究（含简要摘要） - `clinicaltrials_facet_counts` — 整个注册库中各值对应的精确研究数量分布 - `cms_search_datasets` — 查找 CMS Open Payments（Sunshine Act）数据集 - `cms_query_dataset` — 查询 CMS Open Payments 数据存储分发内容（行业→医生付款） - `nppes_lookup_provider` — 查询 CMS/HHS NPPES NPI Registry 中的服务提供者

医疗服务提供者与机构 — CMS（5 个工具）

• cms_medicare_provider_services — Medicare 服务提供者的服务利用情况与付款（用于医疗市场规模测算）
• cms_hospital_compare — CMS Hospital Compare 质量评级
• cms_facility_directory — CMS 疗养院／居家医疗／临终关怀／透析机构名录
• cms_dmepos_suppliers — CMS DMEPOS（耐用医疗设备）供应商名录及 Medicare 支出
• cms_revoked_providers — CMS Medicare 撤销／排除名单（服务提供者合规审查）

网络安全合规 — NVD + CISA KEV + NIST 800-53（3 个工具）

• cve_lookup — 查询 NIST NVD CVE 记录
• cisa_kev_lookup — 筛选 CISA 已知遭利用漏洞目录（具有约束力的 BOD 22-01 修复截止日期）
• nist_800_53_controls — 查询 NIST SP 800-53 Rev 5 安全与隐私控制（按 controlId／family／keyword 查询 FedRAMP/CMMC/RMF 要求文本）

贸易、关税与物流 — USITC · CBP（2 个工具）

• hts_lookup — 查询 USITC《美国协调关税表》中的美国进口关税分类及税率
• cbp_border_wait_times — CBP 陆地边境商用车辆实时等待时间（加拿大与墨西哥口岸；货运／物流）

地理、灾害与州／地方开放数据 — Census · FEMA · NWS · Socrata · CKAN（10 个工具）

• census_geocode_address — 将单行美国地址解析为匹配地址及 Census 地理区域（普查区、国会选区、地点）
• census_geographies_by_coordinates — 将经度／纬度坐标点解析为 Census 地理区域
• fema_disaster_declarations — 按州、类型、事件、年份查询 FEMA 灾害／紧急状态公告
• fema_search_public_assistance — 查询 FEMA 公共援助资助项目
• fema_search_hazard_mitigation — 查询 FEMA 灾害缓解援助项目（HMGP/FMA/PDM/BRIC 向州／地方／部落次级受助方提供的缓解补助；用于灾害韧性，与公共援助灾后恢复不同）
• nws_active_alerts — 查询当前生效的 NWS 天气警报（监视／警告／公告；用于灾害／气候准备，可与 FEMA 工具配合使用）
• socrata_discover_datasets — 按关键词查找 Socrata 数据集 4x4 ID
• socrata_query — 查询允许列表中 Socrata/SODA 开放数据门户的行（54 个精选州／县／市及联邦主机——覆盖 SLED 层级的支票账簿、合同、供应商付款、实时招标）
• ckan_discover_datasets — 按关键词查找 CKAN 数据存储资源 ID
• ckan_query — 查询允许列表中 CKAN 数据存储资源的行（州／市支出／支票账簿）

州／地方采购招标（SLED）— OpenGov · Bonfire · ArcGIS · Tableau · Open Checkbook（8 个工具）

- `opengov_list_governments` — **OpenGov Procurement** 上 525 多个美国州和地方政府的目录（可按州/查询词筛选） - `opengov_search_solicitations` — 某政府的**实时公开招标**（标题、状态［open = 正在接受申请］、截止日期、门户链接）——无需密钥的匿名端点 - `bonfire_list_organizations` — 经过整理并实时验证的美国政府种子目录，包含 **Bonfire (Euna)** 上的 187 个组织 - `bonfire_search_opportunities` — 通过无需密钥的 RSS 获取某组织当前开放的机会（referenceNumber、name、closeDate、link）；RSS 包含完整的开放集合（精确总数） - `arcgis_hub_discover_datasets` — 按关键词发现 ArcGIS Hub 数据集（涵盖 SLED GIS/基础设施/许可证/采购领域，而 Socrata 和 CKAN 未覆盖；这是辅助发现工具，会显示发布方以便核验） - `arcgis_feature_query` — 查询精选许可列表中 **29 个美国政府 ArcGIS REST 要素图层**的行：DC OCP PASS 实时招标；地方政府支票簿/合同；**县级 CIP 项目储备（明尼苏达州亨内平县、北卡罗来纳州夏洛特-梅克伦堡——资本项目储备，而非招标登记册）**；**州 DOT 投标/授标登记册（TX / AK / IA / OK）**；**4 个北达科他州 DOT 联邦弹性资金授标图层**（NDDOT 向县、镇区和城市等地方公共机构发放的资金授标，并非供应商合同或中标投标；由于无法通过无需密钥的方式访问北达科他州全州支票簿和采购门户，因此作为替代数据） - `tableau_view_csv` — 获取精选美国政府 **Tableau Server Guest** 视图的完整 CSV 导出（无需密钥），并对其分页；目前有一个视图：**蒙大拿州 DOA 已授标合同**（约 4,554 条授标记录；数据新鲜度由发布方设置，可能存在延迟） - `open_checkbook_search` — 在精选的 **Socrata Open Expenditures** 支票簿门户中按行搜索供应商付款（无需密钥；支持年份/供应商/部门/费用类别精确匹配筛选）；目前有两个门户：**南达科他州**（约 740,980 笔付款，仅涵盖最近约 3 个财政年度）和 **阿拉斯加州**（41,751 笔付款，仅限 **FY2026**——任何其他年份都会返回 count:0，表示“未发布”，而非零支出）；数据新鲜度由发布方设置，可能存在延迟，因此请按 payment_date desc 排序以查看最新日期

州级开放数据地图——也可作为 MCP 资源获取（samgov://data-map/state-local，任何 MCP 客户端均可通过 resources/read 读取），并收录于 skills/sam-gov/SKILL.md。已验证的最大规模免密钥数据集：德克萨斯州 DIR 合作采购明细 1,070 万行 + TxDOT 实时招标项目 412 个（socrata_query data.texas.gov）、马萨诸塞州 CTHRU 供应商付款约 4,900 万行、弗吉尼亚州 eVA 采购订单明细 169 万行（ckan_query data.virginia.gov）、新泽西州 YourMoney 66 万行、华盛顿州合同和主合同销售额合计 32.5 万行。这些是州级开放数据镜像，并非各州的实时投标门户（TX TxDOT 招标是首个实时招标数据源）。CA、OH、NC、MI 和 TX 非 TxDOT 门户受登录/WAF 限制；FL 和 GA 没有州级开放数据门户（NXDOMAIN）；PA 门户不含采购数据集。

数据集与注册信息发现 — data.gov · get.gov（2 个工具）

• datagov_search_datasets — 搜索 data.gov v4 目录，查找所有发布机构的联邦开放数据集
• search_gov_domains — CISA get.gov 权威 .gov 域名注册信息（查询 .gov 域名所属组织；列出联邦机构并映射 SLED 实体）

小型企业 — SBA（1 个工具）

• sba_size_standard — 查询 6 位 NAICS 对应的 SBA 小型企业规模标准（预留采购资格门槛）

劳动合规 — 美国劳工部（US DOL）（2 个工具）

• dol_list_datasets — 浏览 DOL 执法/合规数据集（WHD、OFCCP 等）——无需密钥的目录
• dol_get_dataset — 获取 DOL 执法记录（WHD 工资与工时 / OFCCP；需要免费的 DOL_API_KEY）

游说与影响力 — 美国参议院 LDA（1 个工具）

- `lda_search_filings` — 参议院游说申报：谁在游说哪个机构、针对什么议题、金额是多少（无需密钥）

服务实用工具 — 密钥发现 · 反馈（2 个工具）

• api_key_status — 列出服务可使用的 API 密钥、哪些是必需的或可选的、注册 URL，以及各密钥当前是否已设置（绝不显示密钥值）
• feedback — 返回预填好的 GitHub 问题链接，用于提交错误报告或功能请求；由你打开链接并自行提交（该工具绝不会发布任何内容）

---

可靠性与离线快照

此服务遵循一条原则：宁可如实报错，也不自信地捏造。 以下内容都只关乎公共数据的可用性，不会绕过访问控制。

优先免密，数据源不可用时会报错。 54 个数据源中有 50 个（153 个工具中有 148 个）无需 API 密钥即可使用；Census 商业模式数据、FRED、BEA 和 DOL 的数据端点需要免费的密钥。数据源遭遇限流、封锁或不可用时，工具会返回类型化错误（rate_limited / upstream_unavailable / schema_drift / …），绝不会编造数据行，也不会把不可用的服务报告为“0 条结果”或“未找到”。真实的空结果与服务中断始终可以区分。

离线快照（默认启用）。 一些参考数据变化缓慢——顶级机构列表、NAICS 顶级目录、USAspending 术语表、SBA 规模标准、最新的美国财政部“精确到便士的债务”数据。默认情况下，如果你所在的出口网络暂时无法访问实时联邦数据源，服务会回退到托管在 raw.githubusercontent.com/cliwant/mcp-sam-gov/snapshots 的公开、每周刷新的快照，其中包含这些变化缓慢的参考数据。只有在实时请求彻底失败（服务中断／IP 信誉封锁）时才会获取快照，正常运行期间不会获取——数据公开，也不收集遥测数据。快照绝不会被标示为实时数据——响应会包含 _meta.dataPath: "snapshot" 和 asOf 时间戳，并强制将 complete 设为关闭状态，因此 AI Agent（以及你）始终能看到数据的时效性。始终遵守限流要求（429），绝不会改用镜像来绕过限流。

• **禁用快照（仅使用实时数据）：**设置 SAMGOV_SNAPSHOT_BASE_URL=off。这样就不会添加任何快照路径，行为与仅使用实时数据的客户端逐字节完全相同。

• **指向你自己的镜像：**将 SAMGOV_SNAPSHOT_BASE_URL 设置为你的基础 URL，即可自行托管快照，而不使用默认的公共镜像。

  { "mcpServers": { "sam-gov": { "command": "mcp-sam-gov",
      "env": { "SAMGOV_SNAPSHOT_BASE_URL": "off" } } } }
  

• 构建快照：在任意干净、未被封锁的出口网络（笔记本／家庭网络／干净的 CI 运行器）上运行 node scripts/build-snapshots.mjs。该脚本会逐个数据源诊断可达性，打印可达性表格，并写入 manifest.json。覆盖范围不完整时，它只刷新可访问的数据源，其他数据源则保留上一次成功生成的文件（保持陈旧但如实，绝不会清空）。只有在所有数据源都无法访问时（出口网络完全被封锁，此时应改用更干净的网络重新运行），脚本才会以非零状态码退出。

• 诚实边界。此机制仅覆盖公共数据的可用性。快照构建器只接收公开且可再分发（公有领域／CC0）的数据，读取器也拒绝提供任何未标记为 accessLevel: "public" 的数据封装。它会遵守限流要求（绝不会绕过 429），不使用代理、不轮换 IP、不绕过身份验证／付费墙／CAPTCHA，并拒绝跳转到其他主机。如果数据源遭到封锁，合乎规范的解决办法是使用更干净的出口网络进行构建，而不是规避封锁。

---

故障排查

症状	解决方法
Claude Desktop 的 🔨 菜单中没有 sam-gov	完全退出 Claude Desktop（Windows 上使用系统托盘；macOS 上使用“退出”菜单），然后重新打开。检查 %APPDATA%\Claude\logs\mcp*.log
command not found: mcp-sam-gov	确认 npm install -g . 已成功；检查 npm 的全局 bin 目录是否在 PATH 中（npm config get prefix）
spawn npx ENOENT（Windows，npx 配置）	宿主未通过 shell 启动 npx，因此 Windows 找不到 npx.cmd。使用 "command": "cmd", "args": ["/c", "npx", "-y", "@cliwant/mcp-sam-gov"]。
执行 npm install -g github:... 后出现 MODULE_NOT_FOUND ...dist/server.js	Windows 上 npm 处理 git 依赖符号链接时存在 bug。请改用克隆仓库并执行 npm install -g . 的方法（路径 3）。
安装期间出现 EPERM: operation not permitted, rmdir	上次安装失败后留下了无法访问的文件。运行 rmdir /s /q "%APPDATA%\npm\node_modules\@cliwant"（如果安装的是早期版本，则使用 @govicon），然后重试。
npm install 因“private repo”／404 失败	仓库现已公开，不应出现此问题。如果出现，请尝试直接运行 git clone https://github.com/cliwant/mcp-sam-gov.git。
工具返回空结果	SAM.gov 会对频繁调用进行速率限制。请等待 1 分钟。或者设置 SAM_GOV_API_KEY，以使用速率更高的认证路径。
“Tool error: USAspending POST returned 400”	通常表示某个字段的类型错误（例如，将财政年度设为字符串）。请在宿主的工具浏览器中检查工具输入架构。

---

用作 TypeScript / JavaScript 库（不使用 MCP）

除了 MCP 服务之外，此软件包还将底层联邦数据客户端导出为可导入的模块。如果你正在构建自己的 SaaS、AI Agent 或命令行工具，并希望以编程方式访问数据，而不启动 MCP 服务，这些模块会很有用。

npm install @cliwant/mcp-sam-gov

// SAM.gov client
import { SamGovClient } from "@cliwant/mcp-sam-gov/sam-gov";

const sam = new SamGovClient(); // keyless
const result = await sam.searchOpportunities({ ncode: "541512", limit: 5 });
const opp = await sam.getOpportunity("5ef3db5daeb54099a96d487783a38bd0");

// USAspending wrappers
import * as usas from "@cliwant/mcp-sam-gov/usaspending";

const recompete = await usas.searchExpiringContracts({
  agency: "Department of Veterans Affairs",
  naics: "541512",
  monthsUntilExpiry: 12,
});
const recipient = await usas.getRecipientProfile("ed02855e-60d7-2540-...-P");

// Federal Register / eCFR / Grants.gov
import * as fedreg from "@cliwant/mcp-sam-gov/federal-register";
import * as ecfr from "@cliwant/mcp-sam-gov/ecfr";
import * as grants from "@cliwant/mcp-sam-gov/grants";

const farResults = await ecfr.search({ query: "SDVOSB", titleNumber: 48 });

这里是 Cliwant 联邦数据库的唯一正式所在地，不存在单独的库软件包。此前的两个仓库（govicon-sam-gov 和 govicon-mcp-sam-gov）已归档并整合到此处。所有客户端代码均位于 src/sam-gov/、src/usaspending.ts、src/federal-register.ts、src/ecfr.ts、src/grants.ts 中。

隐私政策

此服务在本地运行，不收集任何信息——没有遥测、没有分析、无需账户。你的提示词和结果会在你的设备内存中处理，绝不会发送给 Cliwant。每个工具都会通过 HTTPS 直接调用相应的官方政府 API；可选的 API 密钥保存在你的本地环境中，并且只会发送给对应的数据源。请参阅完整的隐私政策（联系方式：[email protected]）。

许可证

MIT——请参阅 LICENSE。

免责声明

这是一个独立的开源项目。它与 General Services Administration、SAM.gov、USAspending.gov、Office of the Federal Register、National Archives、Grants.gov 或任何联邦、州或地方政府机构均无关联，也未获得其认可或赞助。本项目仅使用公开提供的政府开放数据接口；联邦采购、支出和法规数据属于公有领域。