USAspending MCP Server

Read-only Model Context Protocol server for exploring federal spending through the USAspending.gov API.

Use it from Claude Desktop, Codex, Cursor, VS Code, or any MCP-compatible AI tool to ask questions like:

• "Which agencies awarded the most climate-related obligations in FY2025?"
• "Find top recipients for semiconductor-related federal spending."
• "Show spending over time for affordable housing."
• "Get the details behind this USAspending award ID."
• "Search transactions for Department of Energy clean energy awards."

USAspending.gov does not require an API key for these endpoints. This server is intentionally read-only and uses local stdio transport.

Why This Exists

USAspending.gov is powerful, but the API has many endpoints and detailed filter shapes. This MCP server gives AI agents a safer, typed tool layer for common federal-spending workflows:

• agency and recipient lookup
• award and transaction search
• spending aggregation by category, geography, and time
• award profile lookup
• recipient new-award momentum
• safe generic calls for documented /api/v2/ endpoints

It is useful for public-sector market analysis, policy research, impact-investing screens, federal contractor diligence, grant monitoring, and thematic government-spending research.

Tools

Tool	What it does
usaspending_list_toptier_agencies	List federal toptier agencies and summary budgetary fields.
usaspending_autocomplete_recipient	Find recipient names, UEIs, and DUNS values.
usaspending_autocomplete_agency	Find awarding or funding agency offices.
usaspending_search_awards	Search awards/subawards with Advanced Search filters and selected fields.
usaspending_spending_by_category	Aggregate spending by agency, recipient, NAICS, PSC, federal account, state, and more.
usaspending_spending_by_geography	Aggregate by state, county, district, or country.
usaspending_spending_over_time	Aggregate by fiscal year, calendar year, quarter, or month.
usaspending_new_awards_over_time	Count new awards for a recipient by fiscal year, quarter, or month.
usaspending_search_transactions	Search individual transaction records.
usaspending_count_transactions	Count matching transactions by award category.
usaspending_get_award	Fetch detailed award profile data.
usaspending_call_endpoint	Safely call documented read-only /api/v2/ endpoints not covered by a purpose-built tool.

The generic endpoint tool blocks job/file-generating download paths, while allowing the read-only /api/v2/download/count/ preflight endpoint.

Requirements

• Node.js 20 or newer
• npm

No USAspending API key is required.

Install From Source

git clone https://github.com/haydentbs/usaspending-mcp-server.git
cd usaspending-mcp-server
npm install
npm run build

Run a live API smoke test:

npm run smoke

Run the MCP regression suite:

npm run test:mcp

Add It To An AI Tool

Build the project first, then point your MCP client at dist/index.js.

Claude Desktop

Add this to your Claude Desktop MCP config:

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

On macOS, Claude Desktop config is commonly located at:

~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop after editing the config.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.usaspending]
command = "node"
args = ["/absolute/path/to/usaspending-mcp-server/dist/index.js"]

Restart or reload your Codex session so the new MCP namespace is discovered.

Cursor, VS Code, And Other MCP Clients

Most MCP clients use the same server definition shape:

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

If your tool supports per-project MCP config, place the same server definition there. If it supports global config, add it globally.

Example Prompts

After connecting the MCP server, try:

List the top FY2025 awarding agencies for clean energy spending.

Compare FY2021-FY2025 federal spending over time for semiconductor-related awards.

Find the top recipients for wastewater-related spending in FY2025 and show their NAICS concentration.

Search FY2025 Department of Energy contract awards mentioning hydrogen and return award IDs, recipients, amounts, and descriptions.

Example Filters

USAspending Advanced Search filters are passed through as JSON. Most analysis should include an explicit time_period.

Defense contract awards in FY2025:

{
  "filters": {
    "time_period": [{ "start_date": "2024-10-01", "end_date": "2025-09-30" }],
    "agencies": [{ "type": "awarding", "tier": "toptier", "name": "Department of Defense" }],
    "award_type_codes": ["A", "B", "C", "D"]
  },
  "limit": 10,
  "page": 1
}

Spending by NAICS for a keyword:

{
  "category": "naics",
  "filters": {
    "keywords": ["semiconductor"],
    "time_period": [{ "start_date": "2024-10-01", "end_date": "2025-09-30" }]
  }
}

Recipient new-award trend:

{
  "group": "fiscal_year",
  "filters": {
    "recipient_id": "5ad7895c-192b-21cd-8baf-92c6dce0b593-C",
    "time_period": [{ "start_date": "2020-10-01", "end_date": "2025-09-30" }]
  }
}

Notes And Limitations

• USAspending values are obligations/outlays from federal reporting, not company revenue.
• Keyword screens are directional. For production research, combine keywords with NAICS, PSC, agency, assistance listing, and award-type filters.
• Some USAspending endpoints enforce award-type group constraints. For example, award search should not mix contracts, grants, loans, direct payments, and IDVs in a single award_type_codes filter.
• Large federal-spending queries can be slow. The server uses a request timeout, configurable with USASPENDING_TIMEOUT_MS.

Development

npm install
npm run build
npm run test:mcp

Run the server locally:

npm start

Run against TypeScript source during development:

npm run dev

License

MIT