# usaspending-mcp-server [Health: Active]
**Category:** 💻 Developer Tools
**Repository:** https://github.com/cyanheads/usaspending-mcp-server
**GitHub Stars:** 3
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/usaspending-mcp-server
## Description
Access US federal award, recipient, agency, and spending analytics data from USAspending.gov.
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `bunx` (confidence: high):
```json
"mcpServers": {
"usaspending-mcp-server": {
"command": "bunx",
"args": ["@cyanheads/usaspending-mcp-server@latest"]
}
}
```
## Documentation & README
@cyanheads/usaspending-mcp-server
Access US federal award, recipient, agency, and spending analytics data from USAspending.gov via MCP. STDIO or Streamable HTTP.
18 Tools
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/usaspending-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/usaspending-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
[](https://github.com/cyanheads/usaspending-mcp-server/releases/latest/download/usaspending-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=usaspending-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdXNhc3BlbmRpbmctbWNwLXNlcnZlciJdfQ==) [](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)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
**Public Hosted Server:** [https://usaspending.caseyjhand.com/mcp](https://usaspending.caseyjhand.com/mcp)
---
## 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_account`, plus the amount obligated from that account and the funding agency behind it
- Distinct from `usaspending_get_award` `account_obligations_by_defc`, which breaks funding down by Disaster/Emergency Funding code rather than by account
- Pagination via `limit` (max 100) and `page`; `count` in `page_metadata` is the total across pages
- An `award_id` that does not exist returns an empty list rather than an error — the upstream reports no not-found signal for this endpoint
---
### `usaspending_search_recipients`
Search for organizations receiving federal funds by name, UEI, or DUNS.
- 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
- Paginated via `limit` (max 100) and `page`; `page_metadata` reports `total`, `page`, and `has_next` — page through to reach matches beyond the first page
---
### `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)
- `limit` accepts 1–500 (default 50). The upstream endpoint is not paginated — a nationwide county query matches over 3,000 areas — so areas are ranked by `aggregated_amount` descending and capped client-side; `total_areas_available` reports the full match count
- Omitting `filters` entirely aggregates every award type (contracts, IDVs, grants, direct payments, loans, insurance, and unspecified); the substitution is disclosed on the response
- Geographic filters require FIPS codes or 2-letter state abbreviations — use a geocoding server (e.g., Census or OpenStreetMap) to resolve place names first
---
### `usaspending_spending_by_category`
Aggregate spending broken down by a single dimension.
- `category` enum maps to the right sub-route: `naics`, `psc`, `awarding_agency`, `funding_agency`, `cfda`, or `recipient`
- Returns top items with amounts and codes for trend analysis
- Accepts the standard award filter object for scoping to a specific agency, time period, or keyword
- Pagination via `limit` and `page`; no `total` count is available from this endpoint
---
### `usaspending_spending_over_time`
Fetch aggregated spending grouped by time period.
- `group`: `fiscal_year`, `quarter`, or `month`
- Filter by award type, agency, recipient, or keyword to trace trends in a specific area
- `subawards: true` shifts aggregation to the subaward layer
---
### `usaspending_disaster_spending`
Fetch disaster and emergency supplemental spending consolidated from nine+ API endpoints.
- `dimension` enum selects the breakdown axis: `overview`, `agency`, `cfda`, `recipient`, or `geography`
- `spending_type` selects between award-level obligations and outlays (`award`) and total spending including direct non-award amounts (`total`, agency and recipient dimensions only)
- Filter by `def_codes` to isolate a specific emergency appropriation (e.g., COVID-19 = `L`, `M`, `N`, `O`, `P`, `U`)
- Returns obligation, outlay, and award count per row
---
### `usaspending_get_federal_account`
Fetch budget data for a federal account identified by its account code.
- Returns account title, federal account code, agency identifier, parent agency, and bureau
- Includes the fiscal year snapshot: total obligations, gross outlays, and budgetary resources
- `children` breaks the account into its Treasury Account Symbol (TAS) components, each with its own obligated, outlay, and budgetary-resource amounts — one entry per availability period, bounded and returned in full
- Account codes come from `account_number` in `usaspending_search_federal_accounts` results, or `federal_account` in `usaspending_get_award_federal_accounts` results
- For obligations broken down by program activity or object class, use `usaspending_get_federal_account_breakdown`
---
### `usaspending_get_federal_account_breakdown`
Break a federal account's obligations down by program activity or object class.
- `dimension` enum selects the axis: `program_activity` (what the money funds) or `object_class` (what it buys — personnel, supplies, contracts)
- Each row returns the code, name, and obligated amount; `program_activity` rows also carry `type` — `PAC/PAN` (legacy program activity code/name) or `PARK` (Program Activity Reporting Key), both of which can appear for the same account
- Pagination via `limit` (max 100) and `page`; `total` in `page_metadata` is the true row count across pages
- An account code that does not exist returns an empty list rather than an error — unlike `usaspending_get_federal_account`, these routes report no not-found signal
---
### `usaspending_search_federal_accounts`
List and keyword-search federal accounts by agency or title keyword.
- `keyword` filters by account name/title (e.g., `"defense"`, `"transportation"`)
- `agency_identifier` filters to a specific agency by 3-digit code (e.g., `"097"` for DoD) — use `usaspending_list_agencies` to look up codes
- `sort_field` enum: `account_name`, `account_number`, `budgetary_resources` (default), `managing_agency`
- Returns `account_number` (format `"097-8097"`) for chaining into `usaspending_get_federal_account` for full budget detail
- Pagination via `limit` and `page`; `count` in `page_metadata` is the total matches
---
### `usaspending_list_agencies`
List all top-tier federal agencies.
- Returns agency name, abbreviation, `toptier_code`, `agency_slug`, obligated amount, and budget authority amount for the current fiscal year
- Entry point for agency navigation — `toptier_code` is required by `usaspending_get_agency` and agency filters
- Configurable sort and order
---
### `usaspending_autocomplete_filters`
Discover valid code values for award filter fields.
- `type` enum selects the lookup: `naics`, `psc`, `cfda`, `awarding_agency`, or `recipient`
- Returns matching codes and names — use before filtering to find the right code when you only know a description (e.g., "software" → NAICS codes); `recipient` matches also carry `uei`/`duns`
- The `naics` lookup matches official NAICS title text, not colloquial industry language — "software" and "aircraft" resolve, "cybersecurity" and "aircraft maintenance" return nothing. Fall back to the broader industry term the NAICS title would use
- Consolidates five autocomplete endpoints into one tool
- `limit` accepts 1–500 and is enforced client-side — the `recipient` lookup unions three upstream match buckets (name, UEI, DUNS) and can return up to 3x the requested count, so its results are capped before returning; the other four honor `limit` exactly
## Features
Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
- Declarative tool definitions — single file per tool, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats
- Pluggable auth: `none`, `jwt`, `oauth`
- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports
USAspending-specific:
- Full USAspending.gov API v2 coverage — award search, award detail, recipient and agency profiles, spending analytics, disaster spending, and federal accounts
- No authentication required — all data is public domain under the DATA Act
- `usaspending_spending_by_category` consolidates 14 category sub-routes behind a single `category` enum; `usaspending_disaster_spending` consolidates 9+ disaster endpoints behind `dimension` + `spending_type` enums
- `usaspending_get_agency` accepts both `toptier_code` and `agency_slug`, eliminating the intermediate agency-list lookup that award search results would otherwise require
- `usaspending_autocomplete_filters` serves as the code-discovery step before filtering — maps human-readable terms to NAICS, PSC, CFDA, and agency codes
Agent-friendly output:
- Chaining fields on every response — `generated_internal_id`, `agency_slug`, `recipient_hash`, and `account_code` fields are surfaced explicitly so agents can follow the money without parsing identifiers out of display strings
- Pagination metadata on list responses — `page_metadata.has_next` and `page_metadata.page` let agents iterate large result sets without guessing. `page_metadata.total` is carried wherever the upstream endpoint publishes one; `usaspending_get_award_transactions`, `usaspending_get_award_subawards`, and `usaspending_spending_by_category` sit on endpoints that publish none, so `has_next` is the only continuation signal there
- Structured geographic outputs — `shape_code`, `display_name`, `aggregated_amount`, and `per_capita` are typed consistently across state, county, and district views for composable analysis
## Getting started
### Public Hosted Instance
A public instance is available at `https://usaspending.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:
```json
{
"mcpServers": {
"usaspending-mcp-server": {
"type": "streamable-http",
"url": "https://usaspending.caseyjhand.com/mcp"
}
}
}
```
### Self-Hosted / Local
Add the following to your MCP client configuration file. No API key is required — USAspending.gov data is public domain.
```json
{
"mcpServers": {
"usaspending-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/usaspending-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
Or with npx (no Bun required):
```json
{
"mcpServers": {
"usaspending-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/usaspending-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
Or with Docker:
```json
{
"mcpServers": {
"usaspending-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"ghcr.io/cyanheads/usaspending-mcp-server:latest"
]
}
}
}
```
For Streamable HTTP, set the transport and start the server:
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp
```
### Prerequisites
- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
- No API key required — USAspending.gov is a public data platform with no authentication requirement.
### Installation
1. **Clone the repository:**
```sh
git clone https://github.com/cyanheads/usaspending-mcp-server.git
```
2. **Navigate into the directory:**
```sh
cd usaspending-mcp-server
```
3. **Install dependencies:**
```sh
bun install
```
4. **Configure environment (optional):**
```sh
cp .env.example .env
# edit .env if you need to override defaults
```
## Configuration
All configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. No environment variables are required — the defaults work out of the box.
| Variable | Description | Default |
|:---------|:------------|:--------|
| `USASPENDING_BASE_URL` | Base URL for the USAspending.gov API. | `https://api.usaspending.gov/api/v2/` |
| `USASPENDING_TIMEOUT_MS` | HTTP timeout in milliseconds, applied per attempt. | `30000` |
| `USASPENDING_RETRY_BUDGET_MS` | Wall-clock budget covering every retry attempt of one request, so a slow endpoint cannot re-pay the per-attempt timeout on each retry. Accepts 1000–300000. | `1.5 × USASPENDING_TIMEOUT_MS` |
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |
| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path. | `/mcp` |
| `MCP_SESSION_MODE` | Session mode: `auto`, `stateful`, or `stateless`; `auto` resolves to `stateful`. Shipped as `stateless` in both `.env.example` and the Dockerfile — this server holds no per-session state. | `auto` |
| `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments. | — |
| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.). | `info` |
| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |
| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
See [`.env.example`](https://github.com/cyanheads/usaspending-mcp-server/blob/HEAD/.env.example) for the full list of optional overrides.
## Running the server
### Local development
- **Build and run:**
```sh
# One-time build
bun run rebuild
# Run the built server
bun run start:stdio
# or
bun run start:http
```
- **Run checks and tests:**
```sh
bun run devcheck # Lint, format, typecheck, security
bun run test # Vitest test suite
bun run lint:mcp # Validate MCP definitions against spec
```
### Docker
```sh
docker build -t usaspending-mcp-server .
docker run --rm -p 3010:3010 usaspending-mcp-server
```
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/usaspending-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
## Project structure
| Directory | Purpose |
|:----------|:--------|
| `src/index.ts` | `createApp()` entry point — registers tools and inits services. |
| `src/config` | Server-specific environment variable parsing and validation with Zod. |
| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |
| `src/services` | USAspending API client and service layer. |
| `tests/` | Unit and integration tests mirroring `src/`. |
## Development guide
See [`CLAUDE.md`](https://github.com/cyanheads/usaspending-mcp-server/blob/HEAD/CLAUDE.md) for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no `try/catch` in tool logic
- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage
- Register new tools via the barrels in `src/mcp-server/tools/definitions/index.ts`
- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
## Contributing
Issues and pull requests are welcome. Run checks and tests before submitting:
```sh
bun run devcheck
bun run test
```
## License
Apache-2.0 — see [LICENSE](https://github.com/cyanheads/usaspending-mcp-server/blob/HEAD/LICENSE) for details.