Usaspending Mcp Server

cyanheads/usaspending-mcp-server

Wraps the entire USAspending.gov API with 14 tools covering awards, recipients, agencies, and spending analytics. You can search contracts and grants by keyword or filter, pull full award details including subaward chains, profile recipients by UEI, and slice spending data by geography, category, or time period. Includes disaster spending breakdowns (COVID-19, hurricanes) and federal account budget data. The award search returns generated IDs that chain directly into detail and transaction lookups, and recipient hashes link to full org profiles. Useful when you need to trace federal money flows, audit contract hierarchies, or build spending dashboards without parsing CSV dumps.

GitHub stars: 5
tools: 18
transport: STDIO, HTTP
env vars: 6
last updated: Nov 12, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://usaspending.caseyjhand.com/mcp --name usaspending

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http usaspending https://usaspending.caseyjhand.com/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 18 tools

Verified live against the running server on Nov 6, 2026.

usaspending_list_agenciesList top-tier federal agencies with toptier codes, agency slugs, budget authority amounts, and obligation totals for the latest reported period. Returns the full directory unless limit is supplied; optional pagination slices the provider-sorted directory. Use this as the entry...4 params

List top-tier federal agencies with toptier codes, agency slugs, budget authority amounts, and obligation totals for the latest reported period. Returns the full directory unless limit is supplied; optional pagination slices the provider-sorted directory. Use this as the entry...

Parameters* required

limitinteger

Agencies per page; omitted returns the full directory. No maximum.

orderstring

Sort direction: asc or descone of asc · descdefault: asc

pageinteger

Page number when limit is supplied (defaults to page 1); ignored without limit.

sortstring

Sort field: agency_name (alphabetical), budget_authority_amount, obligated_amount, or outlay_amountone of agency_name · budget_authority_amount · obligated_amount · outlay_amountdefault: agency_name

usaspending_autocomplete_filtersLook 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 and sub-agency...3 params

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 and sub-agency...

Parameters* required

limitinteger

Maximum number of results to return (1–500), enforced client-side. Agency matches combine independently capped top-tier then sub-tier buckets, preserving their order without deduplicating names; of...default: 10

search_text*string

Free-text search string — use a description, keyword, or partial code to find matches

type*string

Lookup table to search: naics (industry codes), psc (product/service codes, for the psc_codes filter), cfda (Assistance Listing program numbers, for the assistance_listings filter), awarding_agency...one of naics · psc · cfda · awarding_agency · recipient

usaspending_search_awardsSearch federal awards by keyword, recipient, agency, award type, NAICS code, assistance listing (CFDA) number, PSC, DEF code, location, or date range. Returns ranked award summaries including recipient names, amounts, awarding agencies, and generated award IDs for use with usa...17 params

Search federal awards by keyword, recipient, agency, award type, NAICS code, assistance listing (CFDA) number, PSC, DEF code, location, or date range. Returns ranked award summaries including recipient names, amounts, awarding agencies, and generated award IDs for use with usa...

Parameters* required

agency_namestring

Awarding top-tier or sub-tier agency name — use the matched name from usaspending_autocomplete_filters type=awarding_agency; use toptier_name to select the whole parent department. A sub-tier name...

assistance_listingsarray

Filter by Assistance Listing (CFDA) program numbers, e.g. ["15.507"]: two digits, a dot, then three digits or capital letters (11.67A). Matches an award when any of its listings equals one of these...

award_type_codesarray

Filter by award type codes. All codes must belong to a single group: A/B/C/D (contracts), IDV_A/IDV_B/IDV_B_A/IDV_B_B/IDV_B_C/IDV_C/IDV_D/IDV_E (IDVs), 02/03/04/05/F001/F002 (grants), 06/10/F006/F0...

def_codesarray

Filter by Disaster Emergency Fund Codes (DEF), e.g. ["Z"], or ["L", "M", "N", "O", "P"] for COVID-19: 1–3 letters or digits, sent uppercased — the codes usaspending_disaster_spending takes and usas...

filtersobject

Optional analytics-style filter object mirroring the shape the spending analytics tools accept, for reusing one filter set across tools. When both this object and the equivalent top-level flat filt...

keywordstring

Full-text search across award descriptions, recipient names, and place names; effective keywords need at least three characters without trimming; empty is unset

last_record_sort_valuestring

Keyset-pagination cursor: the last_record_sort_value from a prior response page_metadata. Provide together with last_record_unique_id to fetch the next page past the 50,000-result page-number cap....

last_record_unique_idinteger

Keyset-pagination cursor: the last_record_unique_id from a prior response page_metadata. Provide together with last_record_sort_value.

limitinteger

Maximum results per page (1–100)default: 10

location_filterobject

Filter by place of performance. Takes codes, not place names — use a geocoding server to resolve names to codes first. Blank fields are ignored, and an all-blank object is no location filter. The l...

naics_codesarray

NAICS codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated. Use usa...

orderstring

Sort directionone of asc · descdefault: desc

pageinteger

Page number (1-based). Page-number pagination caps at a 50,000-result offset (page × limit), but the keyset cursor below is only returned while the offset stays under 10,000 — capture the cursor pa...default: 1

psc_codesarray

Filter by Product and Service Codes (PSC), e.g. ["Y1NE"]: 1–4 letters or digits, sent uppercased. A shorter code covers every code under it ("Y1" covers "Y1NE"); several values match any of them. O...

recipient_namestring

Filter by recipient name (partial match); maps to this endpoint's recipient_search_text. This endpoint has no recipient_id filter — use usaspending_search_recipients to look up a recipient by name.

sortstring

Sort field for results. Loans (07/08/F003/F004) sort by Loan Value, Subsidy Cost, Issued Date, Recipient Name, or Awarding Agency, defaulting to Loan Value. Every other group sorts by Award Amount,...one of Award Amount · Total Outlays · Start Date · End Date · Loan Value · Subsidy Cost

time_periodobject

Filter awards by date range (action date). Both blank means no date filter; one blank end is filled and named in the notice.

usaspending_get_awardFetch full details of a federal award by its generated unique award ID. Returns contract or assistance award data including recipient identity (UEI, parent organization, business categories), agency hierarchy, period of performance, place of performance, Assistance Listings wi...1 params

Fetch full details of a federal award by its generated unique award ID. Returns contract or assistance award data including recipient identity (UEI, parent organization, business categories), agency hierarchy, period of performance, place of performance, Assistance Listings wi...

Parameters* required

award_id*string

Generated unique award ID (e.g., CONT_AWD_FA862118F6251_9700_FA862115D6276_9700) — use generated_internal_id from usaspending_search_awards

usaspending_get_award_transactionsList 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 o...5 params

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 o...

Parameters* required

award_id*string

Generated unique award ID (generated_internal_id from usaspending_search_awards)

limitinteger

Maximum transactions per page (1–100)default: 10

orderstring

Sort directionone of asc · descdefault: desc

pageinteger

Page number (1-based)default: 1

sortstring

Sort field for transactionsone of action_date · federal_action_obligation · modification_numberdefault: action_date

usaspending_get_award_subawardsList 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 usasp...5 params

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 usasp...

Parameters* required

award_id*string

Generated unique award ID (generated_internal_id from usaspending_search_awards)

limitinteger

Maximum subawards per page (1–100)default: 10

orderstring

Sort directionone of asc · descdefault: desc

pageinteger

Page number (1-based)default: 1

sortstring

Sort field for subawardsone of subaward_number · description · action_date · amount · recipient_namedefault: action_date

usaspending_get_award_federal_accountsList the Treasury federal accounts that funded an award, with the amount obligated from each and the funding agency behind it. This is the award → appropriation link: each row returns federal_account (AGENCY-MAIN format, e.g. 080-0120) to chain into usaspending_get_federal_acc...3 params

List the Treasury federal accounts that funded an award, with the amount obligated from each and the funding agency behind it. This is the award → appropriation link: each row returns federal_account (AGENCY-MAIN format, e.g. 080-0120) to chain into usaspending_get_federal_acc...

Parameters* required

award_id*string

Award generated_unique_award_id (e.g., CONT_AWD_GSFC0198106DNAS526555_8000_-NONE-_-NONE-) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_ge...

limitinteger

Maximum results per page (1–100)default: 10

pageinteger

Page number (1-based)default: 1

usaspending_get_idv_awardsList child contracts and task/delivery orders placed under an IDV (Indefinite Delivery Vehicle) award. Each row includes the generated_unique_award_id to chain into usaspending_get_award for full detail. The award_id must be the generated_unique_award_id of the parent IDV — ob...6 params

List child contracts and task/delivery orders placed under an IDV (Indefinite Delivery Vehicle) award. Each row includes the generated_unique_award_id to chain into usaspending_get_award for full detail. The award_id must be the generated_unique_award_id of the parent IDV — ob...

Parameters* required

award_id*string

Parent IDV generated_unique_award_id (e.g., CONT_IDV_NNK14MA74C_8000) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award

limitinteger

Maximum results per page (1–100)default: 10

orderstring

Sort directionone of asc · descdefault: desc

pageinteger

Page number (1-based)default: 1

sortstring

Field to sort child awards by (e.g., obligated_amount, period_of_performance_start_date)one of award_type · description · funding_agency · awarding_agency · last_date_to_order · obligated_amountdefault: obligated_amount

typestring

Type of child awards to list: child_awards = task/delivery orders, child_idvs = sub-IDVs, grandchild_awards = orders under sub-IDVsone of child_awards · child_idvs · grandchild_awardsdefault: child_awards

usaspending_search_recipientsSearch for organizations or individuals receiving federal funds by name, UEI (Unique Entity Identifier), or DUNS. Returns recipient hash IDs, UEI/DUNS identifiers, total award amounts, and hierarchy level. Results are paginated — use page to retrieve matches beyond the first p...4 params

Search for organizations or individuals receiving federal funds by name, UEI (Unique Entity Identifier), or DUNS. Returns recipient hash IDs, UEI/DUNS identifiers, total award amounts, and hierarchy level. Results are paginated — use page to retrieve matches beyond the first p...

Parameters* required

award_typestring

Filter by award type category to scope the total amounts returnedone of contracts · grants · direct_payments · loans · other_financial_assistance

keyword*string

Name, UEI, DUNS, or keyword to search for — partial matches are supported. Surrounding whitespace is trimmed; blank text applies no keyword filter and is disclosed.

limitinteger

Maximum results per page (1–100)default: 10

pageinteger

Page number (1-based) — request the next page to retrieve matches beyond the firstdefault: 1

usaspending_get_recipientFetch a recipient's full profile including address, business type codes, parent organization, alternate names, and total transaction and loan amounts. Recipient IDs are hexadecimal 8-4-4-4-12 hashes with a level suffix (-P parent, -C child, -R standalone) from usaspending_sear...2 params

Fetch a recipient's full profile including address, business type codes, parent organization, alternate names, and total transaction and loan amounts. Recipient IDs are hexadecimal 8-4-4-4-12 hashes with a level suffix (-P parent, -C child, -R standalone) from usaspending_sear...

Parameters* required

fiscal_yearinteger

Fiscal year to scope the totals to (e.g., 2024, which runs October 2023 through September 2024). Omit for the trailing 12 months.

recipient_id*string

Recipient hexadecimal 8-4-4-4-12 hash with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P — from usaspending_search_recipients or usaspending_get_award

usaspending_get_agencyFetch an agency's fiscal-year overview including mission, budgetary resources, obligation and outlay totals (for the most recent fiscal year with reported budget data), sub-agency count, and DEF codes for disaster/emergency funding. Also returns a paginated sub-agency breakdow...3 params

Fetch an agency's fiscal-year overview including mission, budgetary resources, obligation and outlay totals (for the most recent fiscal year with reported budget data), sub-agency count, and DEF codes for disaster/emergency funding. Also returns a paginated sub-agency breakdow...

Parameters* required

agency_slugstring

URL-friendly agency slug (e.g., department-of-defense) — from usaspending_list_agencies or award search results. Use either toptier_code or agency_slug, not both.

pageinteger

Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list.default: 1

toptier_codestring

Directory toptier agency code (e.g., 097, 012, 1601) from usaspending_list_agencies. One/two-digit numeric values are padded to three digits (80 becomes 080); three/four-digit codes are preserved....

usaspending_spending_by_geographyAggregate federal spending by state, county, or congressional district. Useful for per-capita analysis, regional comparisons, and mapping federal investment patterns. Filter by keyword, award type, agency, recipient, NAICS code, Assistance Listing, PSC, DEF code, or date range...6 params

Aggregate federal spending by state, county, or congressional district. Useful for per-capita analysis, regional comparisons, and mapping federal investment patterns. Filter by keyword, award type, agency, recipient, NAICS code, Assistance Listing, PSC, DEF code, or date range...

Parameters* required

filtersobject

Optional filters to scope the spending aggregation

geo_layer*string

Geographic granularity: state (states, DC, and territories), county (county-level), or district (congressional district)one of state · county · district

limitinteger

Maximum geographic areas to return, ranked by aggregated_amount descending (1–500). The upstream endpoint is not paginated — it returns every matching area in one response — so this caps client-sid...default: 50

scope*string

Which location to aggregate by: place_of_performance (where work is done) or recipient_location (where the recipient is based)one of place_of_performance · recipient_location

shape_codesarray

Return only these areas (1–500 codes), in the shape_code form this tool returns for geo_layer: 2-letter postal code for state ("NY"), 5-digit state + county FIPS for county ("36117" is Wayne County...

subawardsboolean

Include subaward data instead of prime award datadefault: false

usaspending_spending_by_categoryAggregate 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. Filter by key...4 params

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. Filter by key...

Parameters* required

category*string

Breakdown dimension: naics (industry), psc (product/service code), awarding_agency, awarding_subagency, funding_agency, funding_subagency, cfda (assistance programs), or recipient_duns (recipients)one of naics · psc · awarding_agency · awarding_subagency · funding_agency · funding_subagency

filtersobject

Optional filters to scope the aggregation

limitinteger

Maximum items to return (1–100)default: 10

pageinteger

Page number (1-based)default: 1

usaspending_spending_over_timeFetch aggregated federal obligation amounts grouped by fiscal year, fiscal quarter, or fiscal month. All grouping is relative to the US government fiscal year (Oct–Sep), so fiscal month 1 is October, not January. Filter by award type, agency, recipient, keyword, NAICS code, As...3 params

Fetch aggregated federal obligation amounts grouped by fiscal year, fiscal quarter, or fiscal month. All grouping is relative to the US government fiscal year (Oct–Sep), so fiscal month 1 is October, not January. Filter by award type, agency, recipient, keyword, NAICS code, As...

Parameters* required

filtersobject

Filters to scope the time-series aggregation. Defaults to contract awards when omitted.

group*string

Time grouping: fiscal_year (annual US govt FY: Oct–Sep), quarter (fiscal quarter), or month (fiscal month — an ordinal within the fiscal year, where 1 = October)one of fiscal_year · quarter · month

subawardsboolean

Aggregate subaward data instead of prime award datadefault: false

usaspending_disaster_spendingFetch disaster and emergency supplemental spending broken down by agency, CFDA assistance program, recipient, or geography, or request an overview. Filter by DEF codes to select emergency appropriations, then check amount_coverage before interpreting amounts: award breakdowns...5 params

Fetch disaster and emergency supplemental spending broken down by agency, CFDA assistance program, recipient, or geography, or request an overview. Filter by DEF codes to select emergency appropriations, then check amount_coverage before interpreting amounts: award breakdowns...

Parameters* required

dimension*string

Breakdown axis: overview (top-level totals and DEF code funding), agency (by awarding agency), cfda (by assistance program), recipient (by recipient), geography (by state/county)one of overview · agency · cfda · recipient · geography

filtersobject

Filters — def_codes is required for all non-overview dimensions (agency, cfda, recipient, geography)

limitinteger

Maximum results per page (1–100). Breakdowns rank obligations descending before pagination; geography ranks aggregated_amount. Agency award without award_type_codes collects all provider pages befo...default: 10

pageinteger

Page number (1-based)default: 1

spending_typestring

Data type for the agency dimension: award (award-level obligations and outlays) or total (includes direct non-award spending, plus total budgetary resources). Ignored for cfda, recipient, and overv...one of award · totaldefault: award

usaspending_get_federal_accountFetch a federal account's budget data: total obligations, gross outlays, and budgetary resources, plus the per-Treasury-Account-Symbol (TAS) component breakdown in children. fiscal_year selects a reporting year; omit it for the current federal fiscal year. An empty year retain...2 params

Fetch a federal account's budget data: total obligations, gross outlays, and budgetary resources, plus the per-Treasury-Account-Symbol (TAS) component breakdown in children. fiscal_year selects a reporting year; omit it for the current federal fiscal year. An empty year retain...

Parameters* required

account_code*string

Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts.

fiscal_yearvalue

Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default.

usaspending_get_federal_account_breakdownFetch a federal account's obligations broken down by program activity (what the money funds) or object class (what it buys — personnel, supplies, contracts). Use the dimension parameter to select the axis. fiscal_year scopes financial reporting periods to the full October–Sept...5 params

Fetch a federal account's obligations broken down by program activity (what the money funds) or object class (what it buys — personnel, supplies, contracts). Use the dimension parameter to select the axis. fiscal_year scopes financial reporting periods to the full October–Sept...

Parameters* required

account_code*string

Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts.

dimension*string

Breakdown axis: program_activity (obligations by the program the funds support) or object_class (obligations by the category of goods/services purchased)one of program_activity · object_class

fiscal_yearvalue

Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default.

limitinteger

Maximum results per page (1–100)default: 10

pageinteger

Page number (1-based)default: 1

usaspending_search_federal_accountsList and keyword-search federal accounts by directory toptier code or title keyword. Returns account numbers, names, managing agencies, and budgetary resources. fiscal_year selects the resource amounts, not account membership; omit it for the latest available submission year....7 params

List and keyword-search federal accounts by directory toptier code or title keyword. Returns account numbers, names, managing agencies, and budgetary resources. fiscal_year selects the resource amounts, not account membership; omit it for the latest available submission year....

Parameters* required

agency_identifierstring

Directory toptier_code from usaspending_list_agencies (e.g., "097" for Defense, "1601" for Labor). This differs from the account-prefix agency_identifier returned in account rows (e.g., "016" for L...

fiscal_yearvalue

Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default.

keywordstring

Filter accounts by name or title keyword (e.g., "defense", "transportation")

limitinteger

Maximum results per page (1–100)default: 10

pageinteger

Page number (1-based)default: 1

sort_directionstring

Sort directionone of asc · descdefault: desc

sort_fieldstring

Field to sort results byone of account_name · account_number · budgetary_resources · managing_agencydefault: budgetary_resources

Configuration

MCP_LOG_LEVELdefault: info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault: http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault: 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault: 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault: /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault: none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Readme

@cyanheads/usaspending-mcp-server

Access US federal award, recipient, agency, and spending analytics data from USAspending.gov via MCP. STDIO or Streamable HTTP.

18 Tools

View the full README on GitHub

Details

Repository: github.com/cyanheads/usaspending-mcp-server
Categories: Monitoring & Observability, Data & Analytics
Package: @cyanheads/usaspending-mcp-server
Transport: STDIO, HTTP
Registry: MCP registry, active
Resources: 1
Tools verified: Nov 6, 2026

Related Monitoring & Observability MCP servers

View all

Eds Mcp Serverfocus-gts/eds-mcp-server41 tools for Adobe Edge Delivery Services: read, audit, track, monitor, fix, publish, undo — safely.4stars

ActionsPulsetsviz/github-mcp-server-devopsReal-time GitHub Actions observability: DORA Metrics, Cost Analysis, CI/CD Health dashboards.0stars

Mcprolliinc/rolli-mcpSocial media search, expert discovery, and analytics across X, Reddit, YouTube, and more2stars

Picoli Mcpamaterous/picoli-mcpMCP server for picoli.site - URL shortening and click analytics for AI agents2stars

OntoRamp Decision Intelligencematthewdavisaiarchitect/ontoramp-decision-intelligenceLog, evaluate, and ground AI decisions against authority context. Returns PASS, WARN, or BLOCK.1stars

ACR — Agent Composition Recordstethral-inc/agentregistryInteraction profile registry for AI agents. Log interactions, query behavioral lenses.0stars

Usaspending Mcp Server

Install

Tools

Configuration

Readme

@cyanheads/usaspending-mcp-server

Details

More from cyanheads

Related Monitoring & Observability MCP servers