convez.ai
MCP ServerDados & AnalyticsIntermediário
cyanheads

USAspending MCP Server

cyanheads/usaspending-mcp-server

Acesso via MCP aos dados de gastos federais americanos do USAspending.gov

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece acesso aos dados de gastos, prêmios federais, agências e recipientes do USAspending.gov. Inclui 16 ferramentas para buscas, análises de gastos por geografia e categoria, e dados de contas federais. Compatível com Claude Desktop, Cursor e VS Code.

Instalação

$npx convez-ai cyanheads/usaspending-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
2
Acompanhando
0
Saúde
28%
Último commit
há 5 dias
Versão
v0.7.3
Issues abertas
6
Contribuidores
1

Casos de uso

  • Análise de gastos e alocação de orçamentos federais dos EUA
  • Pesquisa de prêmios federais e contratos por agência ou recipiente
  • Investigação de despesas em desastres e emergências
  • Auditoria e compliance de despesas governamentais

Veredito

MCP server robusto e bem documentado para integração com Claude. Cobre completamente a API do USAspending.gov com 16 ferramentas especializadas. Ideal para análise de gastos federais americanos, mas público específico (EUA).

README

A tradução para o português deste README ainda está na fila.

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

Public Hosted Server: https://usaspending.caseyjhand.com/mcp


Tools

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

ToolDescription
usaspending_search_awardsSearch 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_awardFetch 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_awardsList 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_transactionsList individual transactions (modifications, amendments) on an award. Reveals spending history and obligation changes over time.
usaspending_get_award_subawardsList subaward contracts or grants under a prime award. Reveals the sub-contractor or sub-grantee layer — who actually does the work.
usaspending_search_recipientsSearch for organizations receiving federal funds by name or UEI. Returns recipient IDs, total award amounts, and business type classifications.
usaspending_get_recipientFetch a recipient's profile: address, business types, parent organization, alternate names, and total award amounts by type.
usaspending_get_agencyFetch 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_geographyAggregate federal spending by state, county, or congressional district. Returns per-capita figures when combined with population data.
usaspending_spending_by_categoryAggregate 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_timeFetch aggregated spending by fiscal year, fiscal quarter, or calendar month. Filter by award type, agency, recipient, or keyword to trace trends in a specific area.
usaspending_disaster_spendingFetch 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_accountFetch a federal account's budget data: total obligations, outlays, program activities, and object class breakdown. Account codes appear in award funding details.
usaspending_search_federal_accountsList and keyword-search federal accounts by agency identifier or title keyword. Returns account numbers for chaining into usaspending_get_federal_account.
usaspending_list_agenciesList all top-tier federal agencies with toptier codes, budget authority amounts, and obligation totals. Entry point for agency navigation.
usaspending_autocompleteLook 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 or ID, NAICS code, PSC code, and place of performance
  • Date range filtering — earliest 2007-10-01 via search API
  • Pagination via limit (max 100) and page; page_metadata.hasNext signals more results
  • 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

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

usaspending_search_recipients

Search for organizations receiving federal funds by name or UEI.

  • 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

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

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, budget function, and managing agency
  • Includes fiscal year snapshot with total obligations and outlays
  • Program activity and object class breakdown shows how funds are categorized
  • Account codes appear in account_obligations_by_defc from usaspending_get_award

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

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., "cybersecurity" → NAICS code)
  • Consolidates five autocomplete endpoints into one tool

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 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 all list responses — page_metadata.hasNext, page_metadata.page, and page_metadata.total let agents iterate large result sets without guessing
  • 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.

VariableDescriptionDefault
USASPENDING_BASE_URLBase URL for the USAspending.gov API.https://api.usaspending.gov/api/v2/
USASPENDING_TIMEOUT_MSPer-request HTTP timeout in milliseconds.30000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for the HTTP server.3010
MCP_HTTP_ENDPOINT_PATHHTTP endpoint path./mcp
MCP_PUBLIC_URLPublic origin override for TLS-terminating reverse-proxy deployments.—
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).info
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
STORAGE_PROVIDER_TYPEStorage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.in-memory
OTEL_ENABLEDEnable 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

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools and inits services.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts).
src/servicesUSAspending 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.

Ver o original no GitHub

Bom para

Relacionados