# USAspending MCP

A free, key-less [Model Context Protocol](https://modelcontextprotocol.io) server for
**[USAspending.gov](https://www.usaspending.gov/)** — the U.S. government's official record of
federal spending. Query contracts, grants, loans, recipients, agencies, and geographic
breakdowns directly from the primary source. No API key, no account.

Built with [FastMCP](https://github.com/jlowin/fastmcp). Data covers FY2008-present.

## Tools

| Tool | What it does |
| --- | --- |
| `usaspending_status` | Check API reachability and list supported award categories. |
| `list_agencies` | List/search federal toptier agencies; resolve an agency name to its code. |
| `search_awards` | Search awards (contracts/grants/loans/...) by recipient, agency, keyword, date. |
| `award_count` | Count matching awards broken down by type (contracts, grants, loans, idvs, ...). |
| `award_details` | Full detail for one award (amounts, period of performance, recipient, agencies). |
| `top_recipients` | Top recipients by dollars for an agency + award category over a period. |
| `spending_by_category` | Aggregate spending by recipient, agency, NAICS, PSC, CFDA, geography, etc. |
| `recipient_search` | Find recipients by name; returns UEI / DUNS and a recipient id. |
| `recipient_details` | Profile for one recipient: parent entity, business types, location, totals. |
| `spending_by_geography` | Spending by state / county / district, by recipient location or place of performance. |

## Install

```bash
git clone https://github.com/jsconiers/usaspending-mcp.git
cd usaspending-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python test_usaspending.py   # offline tests
```

## Use with Claude Desktop

Add to `claude_desktop_config.json` (macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "usaspending": {
      "command": "/absolute/path/to/usaspending-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/usaspending-mcp/usaspending_mcp.py"]
    }
  }
}
```

Restart Claude Desktop, then ask things like *"Who are the top DoD contractors this fiscal
year?"*, *"How much has Lockheed Martin been awarded?"*, or *"Show federal contract spending
by state."*

## Award categories

`award_category` accepts a friendly group that expands to USAspending award-type codes:

| Category | Codes |
| --- | --- |
| `contracts` | A, B, C, D |
| `idvs` | IDV_A ... IDV_E |
| `grants` | 02, 03, 04, 05 |
| `direct_payments` | 06, 10 |
| `loans` | 07, 08 |
| `other` | 09, 11, -1 |
| `all` | union of the above |

Pass `award_type_codes` explicitly to override.

## Examples

```
list_agencies(search="defense")                  -> Department of Defense (code 097)
search_awards(recipient="Lockheed Martin")       -> largest contracts + award_internal_id
award_count(recipient="Lockheed Martin")         -> {contracts: 6501, grants: 21, idvs: 233, ...}
top_recipients(agency="Department of Defense")   -> Lockheed, Electric Boat, Raytheon, ...
spending_by_category(category="naics", agency="Department of Defense")
spending_by_geography(geo_layer="state", agency="Department of Defense")
recipient_search(name="Lockheed Martin")         -> UEI / DUNS + recipient_id
```

Typical flow: `search_awards` (or `top_recipients`) to find an award/recipient, then
`award_details` / `recipient_details` for the full record.

## Data source

All data comes from the public USAspending.gov REST API (`https://api.usaspending.gov/`).
Please be considerate with request volume.

## License

MIT — see [LICENSE](LICENSE). Not affiliated with or endorsed by USAspending.gov or the U.S.
government. For informational purposes only.