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">

      

</div>

<div align="center">

  


</div>

<div align="center">

Public Hosted Server: 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:

• 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:

{
  "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.

{
  "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):

{
  "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:

{
  "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:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 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:

git clone https://github.com/cyanheads/usaspending-mcp-server.git

1. Navigate into the directory:

cd usaspending-mcp-server

1. Install dependencies:

bun install

1. Configure environment (optional):

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_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. | false |

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

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 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:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.