US Federal Procurement MCP

Federal contracting intelligence for small businesses — as an MCP server. Search contract opportunities, understand set-asides and NAICS codes, and analyze solicitations for small-business fit and risk — from inside Claude, Cursor, or any MCP client.

This fills the biggest gap in US small-business (SBA) contracting: an LLM trained on the public internet cannot know current contract opportunities or reliably recall the set-aside rules, FAR thresholds, and NAICS structure that determine whether a bid is even worth pursuing. This server makes that real and queryable.

---

Tools (9)

Tool	What it does
search_opportunities	Search federal opportunities by keyword / agency / set-aside / NAICS / state / value / deadline
market_snapshot_tool	Set-aside, sector, agency & value overview + urgent deadlines
analyze_solicitation	Evidence-backed small-business fit assessment (insufficient / mismatch / review / potential) + red-flag scan (bonds, turnover, past-performance)
solicitation_review	Phase-3 deep review: fetches full notice + attachments, combines a bidder capability profile with source-linked extraction (instructions, evaluation factors, clauses, amendments)
look_up_naics	Translate a description into NAICS sectors
look_up_set_aside	Explain a set-aside (Small Business, 8(a), HUBZone, WOSB, SDVOSBC…)
federal_thresholds	Micro-purchase, SAT, Miller Act bond, subcontracting-plan thresholds
opportunity_details	Full record (incl. POC, links, award) + state name for one opportunity — live or sample
opportunity_type	What a SAM.gov type code means (sources sought, solicitation, J&A…)

Everything is deterministic, typed, and honest about its data source.

---

Install & run

python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest tests/ -q      # 84 tests incl. real MCP stdio integration
.venv/bin/us-gov-mcp            # or: .venv/bin/python -m usgovmcp.server

Connect a client

Claude Desktop / Claude Code / Cursor → see configs/mcp-config.json (canonical example: same JSON works for Claude Desktop and Cursor; for Claude Code, use claude mcp add). Set PYTHONPATH to this repo; optionally add a SAM_GOV_API_KEY.

---

Data

• Default: a bundled set of clearly-labeled sample opportunities so it works and is tested with no key.
• Live (SAM.gov): get a free public API key from your SAM.gov account → Account Details → request a public API key. Set SAM_GOV_API_KEY. The provider (SAMGovProvider) already talks to api.sam.gov/opportunities/v2/search and is unit-tested against the real response shape. Live data is never faked — until a key is set, labeled samples are returned.

---

Layout

us-gov-mcp/
├── usgovmcp/
│   ├── server.py       ← FastMCP server wiring all tools
│   ├── knowledge.py    ← NAICS, set-asides, FAR thresholds, red-flag rules
│   ├── analyzer.py     ← evidence-backed fit assessment + red-flag scan
│   ├── solicit.py      ← bidder capability profile + source-linked extraction (Phase 3)
│   ├── providers.py    ← bundled + SAM.gov live providers
│   ├── models.py       ← typed Opportunity / search params / ProviderResult
│   ├── intel.py        ← market-snapshot aggregation
│   └── sample_data.py  ← labeled demo opportunities
├── configs/
├── scripts/smoke.py          ← CI startup check (fails pipeline on broken server)
├── scripts/secret_scan.sh    ← CI gate: blocks committed credentials
├── cache.py                  ← bounded TTL cache (protects SAM.gov quota)
├── tests/                    ← 84 tests incl. real stdio protocol integration
├── constraints.txt           ← tested/locked dependency set for releases
├── CONTRIBUTING.md SECURITY.md LICENSE CHANGELOG.md
├── pyproject.toml            ← also ruff + mypy config
└── README.md

CI runs two jobs: test (Python 3.10/3.11/3.12) and quality (ruff lint + format check, mypy, package build, secret scan). MIT licensed. Not legal advice — always read the full solicitation before bidding.

---

Trust & evidence rules

• analyze_solicitation never produces a confident fit from missing evidence: unknown notices and empty text return insufficient_information.
• Provider results are typed (ProviderResult): ok, no_matches, authentication_error, rate_limited, upstream_error, parse_error, no_key. Asking for sam_gov without a key returns no_key — never a silent, misleading empty list.
• All data is honestly labeled by source (bundled_sample vs sam_gov).