sam-gov-mcp 0.3.6

MCP server for SAM.gov entity registration, exclusion, contract opportunity, and contract award data

sam-gov-mcp

MCP server for SAM.gov entity registration, exclusion/debarment, contract opportunity, and contract award data.

Requires a free SAM.gov API key. Works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Cline, Continue, Zed, etc.).

Tested and hardened through four audit rounds plus a live audit with a real SAM.gov key. 79 regression tests covering 3 P1 live-audit silent-wrong-data bugs, 5 P1 response-shape crashes, and multiple P2 validation gaps fixed. Birthplace of the extra='forbid' cross-fix applied to all 8 MCPs in the suite. See TESTING.md for the full testing record.

What it does

Exposes four SAM.gov REST APIs plus the PSC lookup as 15 MCP tools:

Entity Management (v3)

• lookup_entity_by_uei - Single UEI lookup with configurable response sections
• lookup_entity_by_cage - CAGE code lookup
• search_entities - Flexible entity search (NAICS, PSC, business type, state, name, etc.)
• get_entity_reps_and_certs - FAR/DFARS reps and certs (must be requested explicitly)
• get_entity_integrity_info - FAPIIS proceedings data

Exclusions (v4)

• check_exclusion_by_uei - Single-UEI debarment check
• search_exclusions - Broader exclusion search by name, classification, program, agency, date

Contract Opportunities (v2)

• search_opportunities - Search contract opportunities with full working filter set
• get_opportunity_description - Fetch the HTML description by notice ID

Contract Awards (v1) -- FPDS replacement

• search_contract_awards - Search contract award records (vendor, agency, NAICS, dates, dollars, set-aside, etc.)
• lookup_award_by_piid - Look up all modifications for a single PIID
• search_deleted_awards - Search deleted award records for audit trails

PSC Lookup

• lookup_psc_code - Resolve a PSC code to its full record
• search_psc_free_text - Free-text PSC discovery

Composite workflow

• vendor_responsibility_check - One-shot FAR 9.104-1 check (entity + exclusions in a single tool call)

Authentication

Requires a SAM.gov API key set via the SAM_API_KEY environment variable.

Get a free key at sam.gov/profile/details under "Public API Key."

Account Type	Daily Limit
Non-federal, no SAM role	10/day
Non-federal with SAM role	1,000/day
Federal personal	1,000/day
Federal system account	10,000/day

Important: SAM.gov API keys expire every 90 days. Regenerate at the same profile page and update your env var. This server returns a clear actionable error on 401/403 with regeneration instructions.

Installation

Via uvx (recommended)

uvx sam-gov-mcp

Via pip

pip install sam-gov-mcp

From source

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

Claude Desktop configuration

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

{
  "mcpServers": {
    "sam-gov": {
      "command": "uvx",
      "args": ["sam-gov-mcp"],
      "env": {
        "SAM_API_KEY": "SAM-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. The server appears in your MCP tools panel.

Example prompts

Once configured:

• "Look up Leidos Inc in SAM.gov by UEI QVZMH5JLF274. Check registration status, business types, and whether they have any active exclusions."
• "Find active SDVOSB firms in Virginia with primary NAICS 541512 that are currently registered in SAM."
• "Do a full responsibility check on UEI E1K4E4A29SU5 and tell me whether I can award."
• "Search for all sources sought notices posted in the last 30 days with NAICS 541512."
• "Show me SDVOSB set-aside solicitations for IT services posted this quarter."
• "Get the full description of notice ID [paste ID] and summarize the SOW."
• "Search active exclusions where the excluded party name starts with 'acme'."
• "Search contract awards for Booz Allen Hamilton in fiscal year 2026."
• "Look up all modifications for PIID W912BV22P0112."
• "Find all SDVOSB set-aside contract awards signed this year with NAICS 541512."
• "Show me deleted contract award records for Department of Defense."

Design notes

• Authentication via env var only. SAM_API_KEY is read from the environment on every call. The key never enters Claude's conversation context.
• 90-day expiration awareness. 401/403 errors are translated into an actionable "regenerate at sam.gov/profile/details" message with full context.
• API quirks baked in as safety rails.
  • Entity Management hard cap of size=10 is enforced client-side with a clear error
  • Exclusions uses size not limit (different from other SAM endpoints)
  • Country codes are validated as 3-character ISO alpha-3 (2-char codes return 0 silently)
  • No Accept: application/json header is set (Exclusions returns 406 if present)
  • Bracket/tilde/exclamation characters are preserved in query strings for multi-value params
• Post-filtering for broken parameters. The Opportunities API silently ignores deptname and subtier filters. search_opportunities exposes an agency_keyword parameter that post-filters results by matching fullParentPathName substring.
• includeSections defaults. Entity lookups default to entityRegistration,coreData. Always include entityRegistration alongside any other section or the response has no identification. repsAndCerts and integrityInformation require explicit tool calls (get_entity_reps_and_certs, get_entity_integrity_info) because even includeSections=All doesn't include them.
• Contract Awards response normalization. The Contract Awards API returns different JSON wrapper shapes for populated vs. empty results. All tools normalize this to a consistent {"awardSummary": [...], "totalRecords": int} shape. Error responses are plain text (not JSON), detected and raised as actionable errors.
• Contract Awards pagination. Uses limit/offset (NOT page/size like Entity Management). Max limit is 100. Dates must be MM/dd/yyyy format with bracket ranges [MM/dd/yyyy,MM/dd/yyyy].
• Composite workflow. vendor_responsibility_check collapses a typical FAR 9.104-1 check (entity registration + exclusion lookup) into one tool call, returning a structured flags list for downstream reasoning.

Part of

federal-contracting-mcps — monorepo of 8 MCP servers for federal contracting data. Companion to federal-contracting-skills.

License

MIT