usaspending-mcp

MCP server for the USASpending.gov API — 25 tools for querying federal spending data, tracking government contracts, and researching award recipients.

No API key required. Works with Claude Code, Claude Desktop, Claude.ai, and any MCP-compatible client.

Quick Start

Claude Code (npx)

{
  "mcpServers": {
    "usaspending": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "usaspending-mcp"]
    }
  }
}

Claude Code (local)

{
  "mcpServers": {
    "usaspending": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/usaspending-mcp/dist/index.js"]
    }
  }
}

Remote (Streamable HTTP)

Run on a server:

npx usaspending-mcp --transport http --port 3001

Connect from Claude Desktop or Claude.ai via your reverse proxy URL.

Tools

Search & Discovery (8 tools)

| Tool | Description | |------|-------------| | search_awards | Search federal awards with filters (agency, NAICS, PSC, keywords, date range, award type). Supports pagination. | | search_awards_count | Get result counts by award type before running a full search. | | search_subawards | Search subaward/subcontract records across all prime awards. | | search_by_category | Aggregate spending by dimension (NAICS, PSC, recipient, agency, geography, etc.). | | search_new_awards_over_time | Track new award volume over time by month, quarter, or fiscal year. | | search_spending_over_time | Track spending amounts over time. | | search_spending_by_geography | Break down spending by state, county, or congressional district. | | search_by_transaction | Transaction-level search across all awards. |

Award & IDV Detail (8 tools)

| Tool | Description | |------|-------------| | get_award | Full details for a specific award (recipient, amounts, dates, NAICS/PSC, agency). | | get_award_funding | Funding sources — which federal accounts and agencies fund an award. | | get_award_subawards | Subawards under a prime award. Key for mapping supply chains. | | get_award_transactions | Transaction/modification history for an award. | | get_idv_amounts | Funding summary for an IDV (IDIQ, GWAC, BPA, BOA, FSS). | | get_idv_awards | Task orders under an IDV. Identifies all awardees on a contract vehicle. | | get_idv_activity | Modification and activity history for an IDV. | | get_idv_funding | IDV funding breakdown by federal account. |

Recipient Intelligence (5 tools)

| Tool | Description | |------|-------------| | autocomplete_recipient | Quick recipient name search. First step in finding a company. | | list_recipients | Search and filter recipients with award totals. | | get_recipient | Full company profile — DUNS/UEI, parent company, award history by type. | | get_recipient_children | Child/subsidiary organizations under a parent company. | | get_spending_by_recipient_for_agency | Recipients ranked by award amount from a specific agency. |

Reference Data (4 tools)

| Tool | Description | |------|-------------| | list_agencies | All top-tier federal agencies with codes and metadata. | | search_naics | Search NAICS industry codes by keyword. | | search_psc | Search Product/Service Classification codes by keyword. | | get_naics_hierarchy | Browse the NAICS code tree. |

Filtering

Search tools accept a shared filter object:

{
  "keywords": ["cybersecurity"],
  "award_type_codes": ["D"],
  "time_period": [{ "start_date": "2025-01-01", "end_date": "2025-12-31" }],
  "agencies": [{ "type": "awarding", "tier": "toptier", "name": "Department of Defense" }],
  "naics_codes": ["541512"],
  "psc_codes": ["D399"],
  "recipient_search_text": ["Lockheed"],
  "page": 1,
  "limit": 20,
  "sort": "Award Amount",
  "order": "desc"
}

All filter fields are optional — compose what you need.

Award Type Codes

| Code | Type | |------|------| | A | BPA Call | | B | Purchase Order | | C | Delivery Order | | D | Definitive Contract | | IDV_A | GWAC | | IDV_B_A | IDC / IDIQ | | IDV_B_B | IDC / Indefinite | | IDV_B_C | IDC / Definitive | | IDV_C | FSS | | IDV_D | BOA | | IDV_E | BPA |

Example Workflows

Find DOD cybersecurity contracts:

1. search_naics — find relevant codes (541512, 541519)
2. search_awards — filter by DOD + NAICS codes + award type "D" + date range
3. get_award — deep dive on a specific contract
4. get_recipient — profile the winning company

Map a contractor's supply chain:

1. autocomplete_recipient — find the prime by name
2. get_recipient — get their profile
3. search_awards — find their contracts
4. get_award_subawards — find subcontractors on each contract

Explore an IDIQ/GWAC:

1. search_awards — filter for IDV award types
2. get_idv_awards — list all task order holders
3. get_idv_activity — see recent activity
4. get_recipient — profile each awardee

Development

git clone https://github.com/boejucci/usa-spending-mcp.git
cd usa-spending-mcp
npm install
npm run build
npm run dev        # watch mode

License

MIT