# USAspending MCP Server

Read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for exploring federal spending through the [USAspending.gov API](https://api.usaspending.gov/docs/endpoints).

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

```bash
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:

```bash
npm run smoke
```

Run the MCP regression suite:

```bash
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:

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

On macOS, Claude Desktop config is commonly located at:

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

Restart Claude Desktop after editing the config.

### Codex

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

```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:

```json
{
  "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:

```text
List the top FY2025 awarding agencies for clean energy spending.
```

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

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

```text
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:

```json
{
  "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:

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

Recipient new-award trend:

```json
{
  "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

```bash
npm install
npm run build
npm run test:mcp
```

Run the server locally:

```bash
npm start
```

Run against TypeScript source during development:

```bash
npm run dev
```

## License

MIT