io.github.cyanheads/usaspending-mcp-server
Access US federal award, recipient, agency, and spending analytics data from USAspending.gov.
Open source Repository Open in the app JSON README (API)
About
Access US federal award, recipient, agency, and spending analytics data from USAspending.gov.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- cyanheads
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.4.2
- Stars
- 3
- Forks
- 2
- Last push
- 2026-08-25T02:44:13Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:39
- Updated
- 2026-08-29 03:02:39
- Origin id
io.github.cyanheads/usaspending-mcp-server
README
<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">
[](./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/)
</div>
<div align="center">
[](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)
</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_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). | `<project-root>/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`](./.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`](./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](LICENSE) for details.