@cyanheads/usaspending-mcp-server

List all top-tier federal agencies with toptier codes, agency slugs, budget authority amounts, and obligation totals for the current fiscal year. Use this as the entry point for agency navigation — toptier codes and agency slugs are required inputs for usaspending_get_agency and agency-based filters on spending analysis tools.

Look up valid code values for filter fields by searching free-text descriptions. Use the type parameter to select the lookup table: naics (NAICS industry codes), psc (product/service codes), cfda (CFDA/Assistance Listing program numbers), awarding_agency (agency names and IDs), or recipient (recipient names and IDs). Call this before filtering awards when you know a description but not the exact code. Returns matching codes and names for use in other tool filters.

Search federal awards by keyword, recipient, agency, award type, NAICS code, location, or date range. Returns ranked award summaries including recipient names, amounts, awarding agencies, and generated award IDs for use with usaspending_get_award. Award types: A/B/C/D = contracts, 02/03/04/05 = grants, 06/10 = direct payments, 07/08 = loans, IDV_A/IDV_B/IDV_C/IDV_D/IDV_E = IDVs. Dates must be ISO 8601 (YYYY-MM-DD). Earliest data: 2007-10-01 via search API. DoD contracts have a 90-day publication lag.

Fetch full details of a federal award by its generated unique award ID. Returns contract or assistance award data including recipient info, agency hierarchy, period of performance, place of performance, funding account linkages (account_obligations_by_defc), parent IDV information, and subaward count. Use generated_internal_id values from usaspending_search_awards as input. Recipient hashes can be passed to usaspending_get_recipient; NAICS codes can be used in usaspending_search_awards filters.

List individual transactions (contract modifications, grant amendments) on a federal award. Each transaction represents a change event — obligation modifications, performance period extensions, scope changes, etc. Use this to trace the spending history and obligation changes over the life of an award. Award IDs come from usaspending_search_awards (generated_internal_id field).

List subaward contracts or grants under a prime federal award. Reveals the sub-contractor or sub-grantee layer — the organizations that actually perform the work. Each row shows the subaward number, amount, description, action date, and recipient. Check subaward_count on usaspending_get_award first to confirm subawards exist before calling this tool.

Search for organizations or individuals receiving federal funds by name or UEI (Unique Entity Identifier). Returns recipient IDs (UUID hashes), total award amounts, business type classifications, and location data. Recipient IDs from this tool can be passed to usaspending_get_recipient for full profiles. Recipient level: P = parent organization, C = child entity, R = standalone.

Fetch a recipient's full profile including address, business type classifications, parent organization, alternate names, and total award amounts by category. Recipient IDs are UUID hashes with a level suffix (-P parent, -C child, -R standalone) from usaspending_search_recipients or usaspending_get_award. Optionally scope the award totals to a specific fiscal year and award type. UEI and DUNS values can be used to cross-reference with SAM.gov and SEC EDGAR.

Fetch an agency's current fiscal year overview including mission, budget authority, obligation totals, sub-agency count, and DEF codes for disaster/emergency funding. Also returns sub-agency breakdown with transaction counts. Accepts either a 3-digit toptier_code (e.g., 097 for DoD, 012 for Agriculture) or an agency_slug (e.g., department-of-defense) — both appear in usaspending_list_agencies results and award search results.

Aggregate federal spending by state, county, or congressional district. Useful for per-capita analysis, regional comparisons, and mapping federal investment patterns. Geographic filters accept FIPS codes and 2-letter state abbreviations — NOT place names. Resolve place names to FIPS codes using a geocoding server (Census or OpenStreetMap) before applying location filters. Chain per-capita results with Census population data for meaningful comparisons.

Aggregate federal spending grouped by a specific dimension: NAICS industry code, PSC product/service code, awarding agency, funding agency, CFDA assistance program, or recipient. Returns top items with obligation amounts — useful for trend and breakdown analysis. Chain NAICS codes into usaspending_search_awards filters or usaspending_autocomplete lookups.

Fetch aggregated federal obligation amounts grouped by fiscal year, fiscal quarter, or calendar month. Filter by award type, agency, recipient, keyword, or NAICS code to trace spending trends in a specific area. Returns per-period totals and optional breakdowns by award category (contracts, grants, direct payments, loans, other).

Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, infrastructure law, etc.) broken down by agency, CFDA assistance program, recipient, or geography. Use the dimension parameter to select the breakdown axis: overview (top-level totals), agency, cfda, recipient, or geography. Filter by DEF codes (Disaster/Emergency Funding codes) to isolate a specific emergency appropriation. DEF codes appear in usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields.

Fetch a federal account's budget data: total obligations, gross outlays, and budgetary resources. Federal accounts connect appropriations law to actual agency spending. Account codes appear in usaspending_get_award account_obligations_by_defc field and are formatted as AGENCY-MAIN (e.g., 097-0100 for DoD Operation and Maintenance). Returns account metadata and current fiscal year financial totals.