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>18 Tools</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.4.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-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.14-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

18 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_get_award_federal_accounts` | List the Treasury federal accounts that funded an award, with the amount obligated from each. Returns `federal_account` for chaining into `usaspending_get_federal_account`. |
| `usaspending_search_recipients` | Search for organizations receiving federal funds by name, UEI, or DUNS. Returns recipient hash IDs, UEI/DUNS, total award amounts, and hierarchy level. Paginated — page through with `page`; `page_metadata.total` reports the full match count. |
| `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 fiscal 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, budgetary resources, and the per-Treasury-Account-Symbol component breakdown. Account codes come from `usaspending_search_federal_accounts`. |
| `usaspending_get_federal_account_breakdown` | Break a federal account's obligations down by program activity (what the money funds) or object class (what it buys). Paginated with a total count. |
| `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_filters` | 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, NAICS code, and place of performance
- Date range filtering — earliest 2007-10-01 via search API
- Pagination via `limit` (max 100) and `page`; `page_metadata.has_next` signals more results and is `true` on any full page — the endpoint stops advertising continuation once `page` × `limit` reaches 10,000, so page fullness is the honest signal past that point. Page-number paging caps at a 50,000-result offset — beyond it, continue with keyset pagination using the `last_record_sort_value` + `last_record_unique_id` cursor, which is only returned below the 10,000-result offset and has to be captured before crossing it
- 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. No `total` count is available from this endpoint

---

### `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. No `total` count is available from this endpoint

---

### `usaspending_get_award_federal_accounts`

List the Treasury federal accounts that funded an award — the award → appropriation link.

- `award_id` must be a `generated_unique_award_id` — from `usaspending_search_awards` (`generated_internal_id` field) or `usaspending_get_award`
- Each row returns `federal_account` (AGENCY-MAIN format, e.g. `080-0120`) for chaining into `usaspending_get_federal_accoun