See it in action

👤  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  <co.name@example.gov>  +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…"        

No API key, registration or signup for 148 of the 153 tools. Just plug it in and ask.

Why this exists

The federal data this wraps is public domain. There is no good reason it should cost a five-figure subscription to query.

What this gives Claude (and other AI agents)

153 tools across 54 data sources — keyless-first: only 4 sources (Census business-patterns, FRED, BEA, and DOL's data endpoint) need a free key; the other 50 need none. (An earlier 52-tool build measured roughly p50 ~0.25s / p95 ~0.8s against production federal APIs; latency varies by source and upstream load — treat it as fast, not a benchmarked guarantee.)

How do I install it? Pick the path that matches you.

🟢 Path 1 — Claude Desktop, one-click (no terminal needed)

Best for non-developers. Just download a file and double-click.

1. Download mcp-sam-gov.mcpb from the latest release.
2. Double-click the file. Claude Desktop opens with an "Install Extension" dialog.
3. Click Install.
4. Done. Start a new conversation and ask "Find active SAM.gov opportunities under NAICS 541512".

That's it. No PowerShell, no npm, nothing.

Requires Claude Desktop ≥ 1.0 (which ships its own Node.js runtime).

🟡 Path 2 — Claude Code, one command

If you already use Claude Code (the CLI):

/plugin install cliwant/mcp-sam-gov

This installs the MCP server plus a SKILL.md workflow guide that teaches Claude when + how to use each of the 153 tools.

🔵 Path 3 — Manual install for any MCP host (Codex, Cursor, Continue, Gemini)

For Codex CLI / Cursor / Continue / Gemini CLI / anything that speaks MCP:

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

After install, the binary mcp-sam-gov is on your PATH. Add this to your host config:

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

Specific config locations per host: see Host configurations below.

No global install? Every host config below also has an npx variant (npx -y @cliwant/mcp-sam-gov) that skips the clone and npm install -g. It only needs Node.js.

⚪ Path 4 — Direct path (zero install, just point at the file)

Skip installation entirely:

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

Then point your host config at the absolute path:

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

Host configurations

Each host below shows two variants. Use one of them:

• Global install: "command": "mcp-sam-gov". This works only after npm install -g (Path 3) has put the mcp-sam-gov binary on your PATH.
• No global install (npx): "command": "npx", "args": ["-y", "@cliwant/mcp-sam-gov"]. This needs only Node.js. npx downloads the package from npm on first run and caches it.

Package name: the npm package is scoped: @cliwant/mcp-sam-gov. mcp-sam-gov is only the name of the binary that a global install puts on your PATH. No unscoped mcp-sam-gov package exists on npm, so npx -y mcp-sam-gov fails with a 404. Use npx -y @cliwant/mcp-sam-gov.

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

Global install:

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

No global install (npx):

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

On Windows, if the server fails to start with spawn npx ENOENT in %APPDATA%\Claude\logs\mcp*.log, wrap npx in cmd /c:

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

(Or skip this entirely — use Path 1's .mcpb and it auto-configures.)

Restart Claude Desktop fully (system tray quit on Windows / Quit menu on macOS), then look for the 🔨 icon. You should see "sam-gov (153 tools)".

Claude Code

Per-project .mcp.json, global install:

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

No global install (npx):

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

Or with the 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:

Global install:

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

No global install (npx):

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

Cursor

Settings → MCP → Add new MCP server. Global install:

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

No global install (npx):

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

Continue

~/.continue/config.json, global install:

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

No global install (npx):

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

Gemini CLI

~/.gemini/settings.json, global install:

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

No global install (npx):

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

VS Code

Add a .vscode/mcp.json at your project root (VS Code uses "servers", not "mcpServers"):

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

Or use the one-click badge at the top of this page to install directly from your browser.

Kiro

Use the one-click badge at the top of this page to add the server. Kiro opens an install dialog pre-filled with the npx command.

Anything else

If your host speaks MCP over stdio, point it at mcp-sam-gov (global install) or at npx -y @cliwant/mcp-sam-gov (no global install). No host-specific code.

What questions can I ask?

Once installed, you can ask in natural language. The agent picks the right tool sequence automatically.

Discovery

• "NAICS 541512 의 메릴랜드 입찰 중 30일 안에 마감되는 것 찾아줘"
• "Find active SAM.gov solicitations under NAICS 541512, MD only, closing in 30 days"
• "What's the canonical NAICS code for 'computer systems design'?"

RFP analysis

• "Pull noticeId 5ef3db5daeb54099a96d487783a38bd0 — give me the SOW, contracting officer, and attachments"
• "Show me the full RFP body for that notice"

Competitive landscape

• "Top 5 recipients of VA contracts in NAICS 541519 last fiscal year"
• "Show me Booz Allen's individual awards at DISA"
• "Who are the sub-contractors on Leidos' VA contracts?"
• "What's CMS in USAspending? (resolve the abbreviation)"

Trends & aggregation

• "How has VA 541512 spending trended over the last 5 fiscal years?"
• "Top 10 states by federal contracting spend in 541512"
• "Top PSC categories at DoD by spending"
• "Federal grant programs in cybersecurity by total $"

Agency intelligence (capture brief)

• "Give me a capture brief on VA: mission, FY26 budget breakdown, top sub-agencies"
• "What's VA's transaction volume for FY25?"

Recompete radar

• "VA 541512 contracts expiring in next 12 months over $1M"
• "Pull period of performance for award CONT_AWD_..."

Regulatory & legislative

• "Find FAR sections about SDVOSB set-aside requirements"
• "Turn this RFP's cited FAR/DFARS clause list into a Section L/M compliance matrix"
• "What new VA cybersecurity rules were published this quarter?"
• "Any Federal Register documents on the public-inspection desk from DoD today?"
• "Search Regulations.gov dockets on 'contractor cybersecurity' and pull the public comments"
• "Discover federal open datasets about 'wildfire' on data.gov"
• "Is there a Federal Register doc number 2026-08333? Pull the citation."

Partner & entity vetting

• "Screen 'Acme Defense LLC' against the OFAC sanctions list and SAM exclusions"
• "Look up NPI 1234567890 in NPPES — is this provider active?"
• "Does this subcontractor have adverse Single Audit findings in the Federal Audit Clearinghouse?"
• "How healthy is the bank on cert #3510 — risk ratios and quarterly financials?"
• "Pull this public company's revenue trend and latest 10-K from SEC EDGAR"
• "Any EPA compliance/enforcement flags for this facility?"

Compliance & eligibility

• "What's the SBA small-business size standard for NAICS 541512?"
• "Search the eCFR for the exact text of a rule"
• "What's the US import duty rate (HTS) for lithium-ion batteries?"

Pricing, labor & fiscal

• "GSA CALC ceiling-rate band for a senior systems analyst"
• "Find the SCA wage determination for Baltimore County, MD and give me the fringe rates"
• "How much has CPI-U risen over the last 3 years for an escalation clause?"
• "What's the current total US public debt (Debt to the Penny)?"

Cyber

• "Is CVE-2021-44228 (Log4Shell) on the CISA KEV must-patch list, and what's the due date?"

Health & research funding

• "NIH RePORTER projects on mRNA vaccines funded last year"
• "Recruiting clinical trials for diabetes sponsored by industry"
• "Industry payments to physicians in CA from the CMS Open Payments Research dataset"

Grants

• "Cybersecurity grants posted in the last 30 days"
• "Pull grant id 361238"

Optional — higher rate limits + archives

The MCP server runs keyless by default. For higher SAM.gov rate limits + the full archive (notices older than ~12 months), set SAM_GOV_API_KEY in your host's env block:

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

Get a free key at sam.gov/SAM/pages/public/searchKeyData.jsf. The agent doesn't need to know — the key path is transparent.

DATA_GOV_API_KEY — the api.data.gov / api.gsa.gov family

A handful of sources ride the shared api.data.gov gateway — Congress.gov, GovInfo, Regulations.gov, FAC, GSA per-diem, and the data.gov v4 dataset catalog. They work keyless out of the box via the public DEMO_KEY (a low shared hourly quota). Set DATA_GOV_API_KEY to raise those limits substantially:

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

Get one free (instant, no wait) at api.data.gov/signup. The same key is accepted across all api.data.gov / api.gsa.gov sources. Like the SAM key, it is sent only on the wire (never logged); unset simply means DEMO_KEY. BLS sources similarly accept an optional free BLS_API_KEY to lift their daily quota.

Keys & higher limits — the full inventory

Most tools are keyless. Four sources require a free key — Census (census_business_patterns), FRED (fred_search_series, fred_series_observations), BEA (bea_regional_data), and DOL's data endpoint (dol_get_dataset) — those sources have no keyless tier, so the tool throws without one. (DOL's catalog dol_list_datasets is keyless.) The other keys are optional: they only raise a rate limit or unlock a single filter. Every key below is free.

Two ways to set any key — pick one:

1. Host env block — the "env": { … } object shown in the examples above.
2. A .env file in the server's working directory — configure your keys once:
   code

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

   The server auto-loads .env at startup. A real environment variable always wins over .env (standard precedence), and .env is git-ignored so your keys never get committed.

Ask the server which keys it needs. The keyless api_key_status tool lists every key, whether it's required or optional, the free signup URL + what it unlocks, and whether each is currently configured (a boolean — the key value is never shown). Creating the account at the signup URL is your one manual step; the server automates discovery (api_key_status) and configuration (.env). To confirm a key actually works, call that source's own tool.

Choosing toolsets (smaller context)

By default all 153 tools load — about 74k tokens per session. Clients that pay the full context cost (Claude Desktop, Cursor, raw API) can cut that significantly by loading only the toolsets relevant to the task.

Set the MCP_SAM_GOV_TOOLSETS environment variable to a comma-separated list of toolset names (case-insensitive). Leave it blank (or set it to all) to restore all tools.

Token counts are approximate, measured as the compact JSON character count of each tools/list entry divided by 4. feedback and api_key_status are always loaded in every profile (they help agents report problems and check key health regardless of which toolset is active).

Config examples:

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 (command line):

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): set the Toolsets field in the extension settings dialog (blank = all).

If you call a tool that belongs to an unloaded toolset, the server returns a structured tool_not_loaded error naming the toolset and the exact env var to set. The suggested value is the union of your current loaded sets plus the needed set (e.g. MCP_SAM_GOV_TOOLSETS=core,vetting when you have core loaded and call a vetting tool) so your existing profile is not silently dropped. It never silently returns an empty result.

Staying up to date

npm doesn't notify installed users of new versions, so the server does — minimally. On startup it makes one anonymous request to the public npm registry for its own latest version and, only if a newer one exists, prints a single line to stderr (e.g. a newer version is available: 1.7.0 → 1.8.0). It sends no usage data (a version check, not telemetry), never touches the protocol's stdout, is non-blocking, and stays silent when you're current.

• Update: npm i -g @cliwant/mcp-sam-gov@latest — or just restart if your config uses npx @cliwant/mcp-sam-gov@latest.
• Opt out: set MCP_SAM_GOV_NO_UPDATE_CHECK=1 (or NO_UPDATE_NOTIFIER=1).
• What changed: the releases page + CHANGELOG.

Found a bug? Want a feature? Report it in one step

This server is built to improve from real usage. Because an AI agent (not a human) calls the tools, the feedback path runs through the agent:

• On the two "something may be broken" errors — schema_drift (a federal API changed shape) and upstream_unavailable (an outage) — the error envelope carries a report field: a prefilled GitHub issue link your agent can offer you.
• Or just tell your agent "report a bug" / "this result looks wrong" / "I wish it could do X" — it calls the feedback tool, which returns a prefilled issue link for you to open and submit.

Nothing is ever posted automatically. The server has no token and no account — it only builds the link; you open and submit it. Prefilled links carry only the tool name, error kind, and server version — never your query values. The repo is public, so redact anything sensitive first.

You can also open one directly: New issue — bug / feature / wrong-output templates.

Tool catalog (153 tools)

Grouped by workflow. Keyless-first — most tools need no key; Census business-patterns, FRED, BEA, and DOL's data endpoint require a free key, and a handful of others gain higher limits from an optional free key (noted above). Descriptions are condensed — each tool's own inputSchema carries the full contract and honesty caveats.

State open-data map — also available as an MCP resource (samgov://data-map/state-local, readable by any MCP client via resources/read) and in skills/sam-gov/SKILL.md. Largest verified keyless datasets: Texas DIR cooperative purchase lines 10.7M rows + TxDOT live lettings 412 projects (socrata_query data.texas.gov), Massachusetts CTHRU vendor payments ~49M rows, Virginia eVA PO line items 1.69M rows (ckan_query data.virginia.gov), New Jersey YourMoney 660k rows, Washington contracts + master-contract-sales 325k rows combined. These are state open-data mirrors, not the states' live bid portals (TX TxDOT lettings being the first live solicitation feed). CA, OH, NC, MI, and non-TxDOT TX portals are login/WAF-gated; FL and GA have no state open-data portals (NXDOMAIN); PA's portal carries no procurement datasets.

Reliability & offline snapshots

This server is built around one rule: honest failure over confident fabrication. Everything below is about availability of public data — none of it bypasses access controls.

Keyless-first, and a down source throws. 50 of the 54 sources (148 of the 153 tools) work with no API key; Census business-patterns, FRED, BEA and DOL's data endpoint need a free one. When a source is rate-limited, blocked, or down, the tool returns a typed error (rate_limited / upstream_unavailable / schema_drift / …) — it never invents rows and never reports a DOWN service as "0 results" or "not found". A genuine empty result and an outage are always distinguishable.

Offline snapshots (on by default). Some reference data changes slowly — the toptier-agency list, the top-level NAICS tree, the USAspending glossary, SBA size standards, the latest Treasury "Debt to the Penny." By default, when a live federal source is briefly unreachable from your egress, the server falls back to a public, weekly-refreshed snapshot of that slow-changing reference data, hosted at raw.githubusercontent.com/cliwant/mcp-sam-gov/snapshots. It only fetches on a live hard-failure (an outage / IP-reputation block), never during normal operation — public data, no telemetry. A served snapshot is never presented as live — the response carries _meta.dataPath: "snapshot" plus an asOf timestamp, and complete is forced off, so an AI agent (and you) always see the staleness. A rate limit (429) is always honored, never routed around onto the mirror.

• Disable it (pure live-only): set SAMGOV_SNAPSHOT_BASE_URL=off. Then no snapshot path is ever added and behavior is byte-for-byte identical to a live-only client.

• Point at your own mirror: set SAMGOV_SNAPSHOT_BASE_URL to your base URL to host the snapshots yourself instead of using the public default.

  json

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

• Build the snapshots: run node scripts/build-snapshots.mjs from any clean, non-blocked egress (a laptop / home / clean CI runner). It self-diagnoses per-source reachability, prints a reachability table, and writes a manifest.json. On partial coverage it refreshes only the sources it can reach and leaves the last-good file in place for the rest (stale-but-honest, never blanked). It exits non-zero only when zero sources were reachable (a fully blocked egress — the signal to re-run from a cleaner one).

• The honest boundary. This covers public-data availability only. The snapshot builder ingests only public, redistributable (public-domain / CC0) data, and the reader refuses to serve any envelope not marked accessLevel: "public". It honors rate limits (a 429 is never routed around), uses no proxies, no IP rotation, no auth/paywall/CAPTCHA bypass, and refuses off-host redirects. If a source is blocked, the honest remedy is to build from a cleaner egress — not to evade the block.

Troubleshooting

Use as a TypeScript / JavaScript library (no MCP)

Beyond the MCP server, this package also exports the underlying federal-data clients as importable modules. Useful if you're building your own SaaS, AI agent, or CLI and want programmatic access without spawning an MCP server.

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 });

This is the canonical home for the Cliwant federal-data libraries — there is no separate library package. Two earlier repos (govicon-sam-gov and govicon-mcp-sam-gov) have been archived and consolidated here. All client code lives in src/sam-gov/, src/usaspending.ts, src/federal-register.ts, src/ecfr.ts, src/grants.ts.

Privacy Policy

This server runs locally and collects nothing — no telemetry, no analytics, no accounts. Your prompts and results are processed in memory on your machine and are never sent to Cliwant. Each tool calls the relevant official government API directly over HTTPS; optional API keys stay in your local environment and are sent only to that source. See the full Privacy Policy (contact: seungdo.keum@cliwant.com).

License

MIT — see LICENSE.

Disclaimer

This is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by the General Services Administration, SAM.gov, USAspending.gov, the Office of the Federal Register, the National Archives, Grants.gov, or any federal, state, or local government agency. It uses only publicly available government open-data endpoints; federal procurement, spending, and regulation data is in the public domain.