\n\n[](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)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\n18 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:\n\n| Tool | Description |\n|:---|:---|\n| `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. |\n| `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. |\n| `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`. |\n| `usaspending_get_award_transactions` | List individual transactions (modifications, amendments) on an award. Reveals spending history and obligation changes over time. |\n| `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. |\n| `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`. |\n| `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. |\n| `usaspending_get_recipient` | Fetch a recipient's profile: address, business types, parent organization, alternate names, and total award amounts by type. |\n| `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. |\n| `usaspending_spending_by_geography` | Aggregate federal spending by state, county, or congressional district. Returns per-capita figures when combined with population data. |\n| `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. |\n| `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. |\n| `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. |\n| `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`. |\n| `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. |\n| `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`. |\n| `usaspending_list_agencies` | List all top-tier federal agencies with toptier codes, budget authority amounts, and obligation totals. Entry point for agency navigation. |\n| `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. |\n\n### `usaspending_search_awards`\n\nSearch for federal awards across contracts, grants, loans, direct payments, and IDVs.\n\n- Full-text keyword search across award descriptions, recipient names, and locations\n- Filter by award type codes (`A/B/C/D` = contracts, `02/03/04/05` = grants, `06/10` = direct payments, `07/08` = loans, `IDV_*` = IDVs)\n- Filter by awarding or funding agency (toptier or subtier), recipient name, NAICS code, and place of performance\n- Date range filtering — earliest 2007-10-01 via search API\n- 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\n- Returns `generated_internal_id` for chaining to `usaspending_get_award` and `agency_slug` for chaining to `usaspending_get_agency`\n\n---\n\n### `usaspending_get_award`\n\nFetch complete details for a single federal award by its generated ID.\n\n- Returns type, description, total obligation, date signed, and subaward count\n- Exposes `recipient.recipient_hash` for chaining to `usaspending_get_recipient`\n- Exposes `parent_award.generated_unique_award_id` for traversing IDV parent chains\n- Includes NAICS code and product/service code from the latest transaction\n- Returns `account_obligations_by_defc` linking the award to specific disaster/emergency appropriations\n- Award IDs use the `generated_unique_award_id` format (e.g., `CONT_AWD_FA862118F6251_9700_...`)\n\n---\n\n### `usaspending_get_idv_awards`\n\nList child contracts and orders placed under an IDV (Indefinite Delivery Vehicle) award.\n\n- `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`\n- `type` selects what to list: `child_awards` (task/delivery orders), `child_idvs` (sub-IDVs), or `grandchild_awards`\n- Each row returns `generated_unique_award_id` for chaining into `usaspending_get_award` for full detail\n- Pagination via `limit` and `page`; note: no `total` count is available from this endpoint\n- An invalid `award_id` or an IDV with no children of the requested type returns an empty result set\n\n---\n\n### `usaspending_get_award_transactions`\n\nList obligation history and modifications for an award.\n\n- Each row is one transaction: `action_date`, `federal_action_obligation`, `modification_number`, and description\n- Pagination via `limit` and `page`; configurable sort and order. No `total` count is available from this endpoint\n\n---\n\n### `usaspending_get_award_subawards`\n\nList subawards under a prime contract or grant.\n\n- Each row covers: subaward number, description, action date, amount, and recipient name\n- Reveals the supply chain below the prime — who actually performs the work\n- Pagination via `limit` and `page`; configurable sort and order. No `total` count is available from this endpoint\n\n---\n\n### `usaspending_get_award_federal_accounts`\n\nList the Treasury federal accounts that funded an award — the award → appropriation link.\n\n- `award_id` must be a `generated_unique_award_id` — from `usaspending_search_awards` (`generated_internal_id` field) or `usaspending_get_award`\n- 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\n- Distinct from `usaspending_get_award` `account_obligations_by_defc`, which breaks funding down by Disaster/Emergency Funding code rather than by account\n- Pagination via `limit` (max 100) and `page`; `count` in `page_metadata` is the total across pages\n- 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\n\n---\n\n### `usaspending_search_recipients`\n\nSearch for organizations receiving federal funds by name, UEI, or DUNS.\n\n- Returns recipient IDs (UUID hashes with level suffix: `-P` parent, `-C` child, `-R` root), UEI, DUNS, name, recipient level, and total award amount\n- `results[].id` chains to `usaspending_get_recipient`; `uei` and `duns` chain to SAM.gov or SEC EDGAR\n- Paginated via `limit` (max 100) and `page`; `page_metadata` reports `total`, `page`, and `has_next` — page through to reach matches beyond the first page\n\n---\n\n### `usaspending_get_recipient`\n\nFetch a recipient's full profile.\n\n- Returns address, business type classifications, parent organization, alternate names\n- Optionally scope to a specific fiscal year and award type\n- Requires the UUID-based recipient ID from `usaspending_search_recipients`\n\n---\n\n### `usaspending_get_agency`\n\nFetch an agency's current fiscal year overview.\n\n- Returns mission, budget authority amount, obligation amount, sub-agency count, and DEF codes\n- 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\n- Includes sub-agency breakdown with transaction counts\n\n---\n\n### `usaspending_spending_by_geography`\n\nAggregate federal spending by geographic unit.\n\n- `scope`: `place_of_performance` or `recipient_location`\n- `geo_layer`: `state`, `county`, or `district`\n- Returns `shape_code`, `display_name`, `aggregated_amount`, and `per_capita` (when `population` is available)\n- `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\n- Omitting `filters` entirely aggregates every award type (contracts, IDVs, grants, direct payments, loans, insurance, and unspecified); the substitution is disclosed on the response\n- Geographic filters require FIPS codes or 2-letter state abbreviations — use a geocoding server (e.g., Census or OpenStreetMap) to resolve place names first\n\n---\n\n### `usaspending_spending_by_category`\n\nAggregate spending broken down by a single dimension.\n\n- `category` enum maps to the right sub-route: `naics`, `psc`, `awarding_agency`, `funding_agency`, `cfda`, or `recipient`\n- Returns top items with amounts and codes for trend analysis\n- Accepts the standard award filter object for scoping to a specific agency, time period, or keyword\n- Pagination via `limit` and `page`; no `total` count is available from this endpoint\n\n---\n\n### `usaspending_spending_over_time`\n\nFetch aggregated spending grouped by time period.\n\n- `group`: `fiscal_year`, `quarter`, or `month`\n- Filter by award type, agency, recipient, or keyword to trace trends in a specific area\n- `subawards: true` shifts aggregation to the subaward layer\n\n---\n\n### `usaspending_disaster_spending`\n\nFetch disaster and emergency supplemental spending consolidated from nine+ API endpoints.\n\n- `dimension` enum selects the breakdown axis: `overview`, `agency`, `cfda`, `recipient`, or `geography`\n- `spending_type` selects between award-level obligations and outlays (`award`) and total spending including direct non-award amounts (`total`, agency and recipient dimensions only)\n- Filter by `def_codes` to isolate a specific emergency appropriation (e.g., COVID-19 = `L`, `M`, `N`, `O`, `P`, `U`)\n- Returns obligation, outlay, and award count per row\n\n---\n\n### `usaspending_get_federal_account`\n\nFetch budget data for a federal account identified by its account code.\n\n- Returns account title, federal account code, agency identifier, parent agency, and bureau\n- Includes the fiscal year snapshot: total obligations, gross outlays, and budgetary resources\n- `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\n- Account codes come from `account_number` in `usaspending_search_federal_accounts` results, or `federal_account` in `usaspending_get_award_federal_accounts` results\n- For obligations broken down by program activity or object class, use `usaspending_get_federal_account_breakdown`\n\n---\n\n### `usaspending_get_federal_account_breakdown`\n\nBreak a federal account's obligations down by program activity or object class.\n\n- `dimension` enum selects the axis: `program_activity` (what the money funds) or `object_class` (what it buys — personnel, supplies, contracts)\n- 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\n- Pagination via `limit` (max 100) and `page`; `total` in `page_metadata` is the true row count across pages\n- 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\n\n---\n\n### `usaspending_search_federal_accounts`\n\nList and keyword-search federal accounts by agency or title keyword.\n\n- `keyword` filters by account name/title (e.g., `\"defense\"`, `\"transportation\"`)\n- `agency_identifier` filters to a specific agency by 3-digit code (e.g., `\"097\"` for DoD) — use `usaspending_list_agencies` to look up codes\n- `sort_field` enum: `account_name`, `account_number`, `budgetary_resources` (default), `managing_agency`\n- Returns `account_number` (format `\"097-8097\"`) for chaining into `usaspending_get_federal_account` for full budget detail\n- Pagination via `limit` and `page`; `count` in `page_metadata` is the total matches\n\n---\n\n### `usaspending_list_agencies`\n\nList all top-tier federal agencies.\n\n- Returns agency name, abbreviation, `toptier_code`, `agency_slug`, obligated amount, and budget authority amount for the current fiscal year\n- Entry point for agency navigation — `toptier_code` is required by `usaspending_get_agency` and agency filters\n- Configurable sort and order\n\n---\n\n### `usaspending_autocomplete_filters`\n\nDiscover valid code values for award filter fields.\n\n- `type` enum selects the lookup: `naics`, `psc`, `cfda`, `awarding_agency`, or `recipient`\n- 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`\n- 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\n- Consolidates five autocomplete endpoints into one tool\n- `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\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per tool, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nUSAspending-specific:\n\n- Full USAspending.gov API v2 coverage — award search, award detail, recipient and agency profiles, spending analytics, disaster spending, and federal accounts\n- No authentication required — all data is public domain under the DATA Act\n- `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\n- `usaspending_get_agency` accepts both `toptier_code` and `agency_slug`, eliminating the intermediate agency-list lookup that award search results would otherwise require\n- `usaspending_autocomplete_filters` serves as the code-discovery step before filtering — maps human-readable terms to NAICS, PSC, CFDA, and agency codes\n\nAgent-friendly output:\n\n- 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\n- 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\n- Structured geographic outputs — `shape_code`, `display_name`, `aggregated_amount`, and `per_capita` are typed consistently across state, county, and district views for composable analysis\n\n## Getting started\n\n### Public Hosted Instance\n\nA public instance is available at `https://usaspending.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:\n\n```json\n{\n \"mcpServers\": {\n \"usaspending-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://usaspending.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-Hosted / Local\n\nAdd the following to your MCP client configuration file. No API key is required — USAspending.gov data is public domain.\n\n```json\n{\n \"mcpServers\": {\n \"usaspending-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/usaspending-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"usaspending-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/usaspending-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"usaspending-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"ghcr.io/cyanheads/usaspending-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- No API key required — USAspending.gov is a public data platform with no authentication requirement.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/usaspending-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd usaspending-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment (optional):**\n\n```sh\ncp .env.example .env\n# edit .env if you need to override defaults\n```\n\n## Configuration\n\nAll 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.\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `USASPENDING_BASE_URL` | Base URL for the USAspending.gov API. | `https://api.usaspending.gov/api/v2/` |\n| `USASPENDING_TIMEOUT_MS` | HTTP timeout in milliseconds, applied per attempt. | `30000` |\n| `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` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |\n| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path. | `/mcp` |\n| `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` |\n| `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments. | — |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t usaspending-mcp-server .\ndocker run --rm -p 3010:3010 usaspending-mcp-server\n```\n\nThe 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.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools and inits services. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |\n| `src/services` | USAspending API client and service layer. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools via the barrels in `src/mcp-server/tools/definitions/index.ts`\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n",
"bytes": 25507,
"sha": "d180ab7933d06e9f52e65c9c41a61cc577c77cd846ce5ee8fd9c5ed366f33193",
"repo_slug": "cyanheads/usaspending-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_usaspending_mcp_serv_f781a533/readme"
}