usaspending-mcp-server

<div align="center">
  <h1>@cyanheads/usaspending-mcp-server</h1>
  <p><b>Access US federal award, recipient, agency, and spending analytics data from USAspending.gov via MCP. STDIO or Streamable HTTP.</b>
  <div>16 Tools</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.2.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/usaspending-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/usaspending-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/usaspending-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/usaspending-mcp-server/releases/latest/download/usaspending-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=usaspending-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdXNhc3BlbmRpbmctbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22usaspending-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fusaspending-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://usaspending.caseyjhand.com/mcp](https://usaspending.caseyjhand.com/mcp)

</div>

---

## Tools

16 tools covering the full USAspending.gov API surface — award discovery and detail, recipient and agency profiles, spending analytics (by geography, category, and time), disaster/emergency spending, and federal account data:

| Tool | Description |
|:---|:---|
| `usaspending_search_awards` | Search federal awards by keyword, recipient, agency, award type, NAICS code, location, or date range. Returns ranked award summaries with recipient names, amounts, agencies, and award IDs for chaining. |
| `usaspending_get_award` | Fetch full details of a federal award by its generated ID. Returns contract or assistance data, parent IDV info, subaward count, and funding account linkages. |
| `usaspending_get_idv_awards` | List child contracts and task/delivery orders placed under an IDV award. Each row includes a `generated_unique_award_id` for chaining into `usaspending_get_award`. |
| `usaspending_get_award_transactions` | List individual transactions (modifications, amendments) on an award. Reveals spending history and obligation changes over time. |
| `usaspending_get_award_subawards` | List subaward contracts or grants under a prime award. Reveals the sub-contractor or sub-grantee layer — who actually does the work. |
| `usaspending_search_recipients` | Search for organizations receiving federal funds by name or UEI. Returns recipient IDs, total award amounts, and business type classifications. |
| `usaspending_get_recipient` | Fetch a recipient's profile: address, business types, parent organization, alternate names, and total award amounts by type. |
| `usaspending_get_agency` | Fetch an agency's fiscal year overview: mission, budget authority, obligation totals, sub-agency count, and DEF codes. Accepts a 3-digit `toptier_code` or an `agency_slug` from award search results. |
| `usaspending_spending_by_geography` | Aggregate federal spending by state, county, or congressional district. Returns per-capita figures when combined with population data. |
| `usaspending_spending_by_category` | Aggregate spending grouped by NAICS code, PSC code, awarding agency, funding agency, CFDA program, or recipient. Returns top items with amounts for trend and breakdown analysis. |
| `usaspending_spending_over_time` | Fetch aggregated spending by fiscal year, fiscal quarter, or calendar month. Filter by award type, agency, recipient, or keyword to trace trends in a specific area. |
| `usaspending_disaster_spending` | Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, etc.) broken down by agency, CFDA program, recipient, or geography. Filter by DEF codes to isolate a specific appropriation. |
| `usaspending_get_federal_account` | Fetch a federal account's budget data: total obligations, outlays, program activities, and object class breakdown. Account codes appear in award funding details. |
| `usaspending_search_federal_accounts` | List and keyword-search federal accounts by agency identifier or title keyword. Returns account numbers for chaining into `usaspending_get_federal_account`. |
| `usaspending_list_agencies` | List all top-tier federal agencies with toptier codes, budget authority amounts, and obligation totals. Entry point for agency navigation. |
| `usaspending_autocomplete` | Look up valid code values for filter fields: NAICS, PSC, CFDA, recipient names, or agency names. Use before filtering to discover the right code from a description. |

### `usaspending_search_awards`

Search for federal awards across contracts, grants, loans, direct payments, and IDVs.

- Full-text keyword search across award descriptions, recipient names, and locations
- Filter by award type codes (`A/B/C/D` = contracts, `02/03/04/05` = grants, `06/10` = direct payments, `07/08` = loans, `IDV_*` = IDVs)
- Filter by awarding or funding agency (toptier or subtier), recipient name or ID, NAICS code, PSC code, and place of performance
- Date range filtering — earliest 2007-10-01 via search API
- Pagination via `limit` (max 100) and `page`; `page_metadata.hasNext` signals more results
- Returns `generated_internal_id` for chaining to `usaspending_get_award` and `agency_slug` for chaining to `usaspending_get_agency`

---

### `usaspending_get_award`

Fetch complete details for a single federal award by its generated ID.

- Returns type, description, total obligation, date signed, and subaward count
- Exposes `recipient.recipient_hash` for chaining to `usaspending_get_recipient`
- Exposes `parent_award.generated_unique_award_id` for traversing IDV parent chains
- Includes NAICS code and product/service code from the latest transaction
- Returns `account_obligations_by_defc` linking the award to specific disaster/emergency appropriations
- Award IDs use the `generated_unique_award_id` format (e.g., `CONT_AWD_FA862118F6251_9700_...`)

---

### `usaspending_get_idv_awards`

List child contracts and orders placed under an IDV (Indefinite Delivery Vehicle) award.

- `award_id` must be the `generated_unique_award_id` of the parent IDV — from `usaspending_search_awards` (`generated_internal_id` field) or from `usaspending_get_award`
- `type` selects what to list: `child_awards` (task/delivery orders), `child_idvs` (sub-IDVs), or `grandchild_awards`
- Each row returns `generated_unique_award_id` for chaining into `usaspending_get_award` for full detail
- Pagination via `limit` and `page`; note: no `total` count is available from this endpoint
- An invalid `award_id` or an IDV with no children of the requested type returns an empty result set

---

### `usaspending_get_award_transactions`

List obligation history and modifications for an award.

- Each row is one transaction: `action_date`, `federal_action_obligation`, `modification_number`, and description
- Pagination via `limit` and `page`; configurable sort and order

---

### `usaspending_get_award_subawards`

List subawards under a prime contract or grant.

- Each row covers: subaward number, description, action date, amount, and recipient name
- Reveals the supply chain below the prime — who actually performs the work
- Pagination via `limit` and `page`; configurable sort and order

---

### `usaspending_search_recipients`

Search for organizations receiving federal funds by name or UEI.

- Returns recipient IDs (UUID hashes with level suffix: `-P` parent, `-C` child, `-R` root), UEI, DUNS, name, recipient level, and total award amount
- `results[].id` chains to `usaspending_get_recipient`; `uei` and `duns` chain to SAM.gov or SEC EDGAR

---

### `usaspending_get_recipient`

Fetch a recipient's full profile.

- Returns address, business type classifications, parent organization, alternate names
- Optionally scope to a specific fiscal year and award type
- Requires the UUID-based recipient ID from `usaspending_search_recipients`

---

### `usaspending_get_agency`

Fetch an agency's current fiscal year overview.

- Returns mission, budget authority amount, obligation amount, sub-agency count, and DEF codes
- Accepts either a 3-digit `toptier_code` (e.g., `097` for DoD) or an `agency_slug` (e.g., `department-of-defense`) — slugs appear in award search results, eliminating an intermediate lookup
- Includes sub-agency breakdown with transaction counts

---

### `usaspending_spending_by_geography`

Aggregate federal spending by geographic unit.

- `scope`: `place_of_performance` or `recipient_location`
- `geo_layer`: `state`, `county`, or `district`
- Returns `shape_code`, `display_name`, `aggregated_amount`, and `per_capita` (when `population` is available)
- Geographic filters require FIPS codes or 2-letter state abbreviations — use a geocoding server (