Usaspending MCP Server

@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

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

Overview

Where federal money goes, from USAspending.gov: awards, recipients, agencies, and spending. Search and trace awards down to transactions, subawards, and funding accounts; profile recipients and agencies; and aggregate spending by geography, category, time, and disaster appropriation.

Tools

Research guide

The usaspending-guide covers recipient research, award-to-account funding traces, and spending comparisons across periods and emergency appropriations. Plugin installs discover it in skills/; MCP clients can read skill://usaspending-guide/SKILL.md through the Skills extension. There are no domain-data resources.

Capability reference

usaspending_list_agencies tool

• Takes sort (agency_name, budget_authority_amount, obligated_amount, outlay_amount) and order; returns every agency unless an optional positive limit is supplied. With limit, page defaults to 1; without it, page is ignored. total always counts the full directory and has_next appears only when paginating
• Rows carry toptier_code and agency_slug, both accepted by usaspending_get_agency, plus budget_authority_amount, obligated_amount, and outlay_amount for the latest reported period. fiscal_year and fiscal_quarter preserve the provider's reporting labels when present

usaspending_autocomplete_filters tool

• type (naics, psc, cfda, awarding_agency, recipient) plus search_text; limit 1–500, default 10
• Rows carry code and name, and uei / duns for recipients; no match fails as no_match. A cfda code goes in assistance_listings and a psc code in psc_codes on usaspending_search_awards and the three spending analytics tools
• Agency rows carry the matched agency's own name, abbreviation, and tier (toptier or subtier), its parent's toptier_name and toptier_code, and subtier_code when supplied. Pass name to agency_name on award search or spending analytics to match that agency; pass toptier_name for the whole department. Agency results combine top-tier then sub-tier matches under one limit; office matches are excluded
• naics matches official NAICS title text: "software" resolves, "cybersecurity" does not, so search with the industry term a title would use

usaspending_search_awards tool

• Filters:
• keyword, agency_name, recipient_name, naics_codes
• assistance_listings: Assistance Listing numbers such as 93.866, from usaspending_autocomplete_filters type: cfda
• psc_codes: 1–4 characters, where a prefix such as Y1 covers the codes under it; contracts and IDVs only
• def_codes: Disaster Emergency Fund Codes such as Z (PSC and DEF codes are sent uppercased)
• time_period: YYYY-MM-DD from 2007-10-01 on; either end may be given alone
• location_filter: country (default USA; a territory code such as PRI becomes USA plus its state), state (a postal or 2-digit FIPS code, FM/MH/PW/UM and armed-forces AA/AE/AP included, or under another country its own 2-letter subdivision code such as ON with CAN), and county (3 digits with state, or the 5-digit FIPS code alone); echoed as applied_location
• award_type_codes: defaults to contracts (A–D) and must stay in one group — IDVs IDV_A–IDV_E; grants 02–05/F001/F002; direct payments 06/10/F006/F007; loans 07/08/F003/F004; other assistance 09/11/-1/F005/F008/F009/F010
• limit: up to 100
• Rows carry generated_internal_id for usaspending_get_award and agency_slug for usaspending_get_agency; loan rows carry loan_value, subsidy_cost, and issued_date in place of amounts and dates. There is no total, and page_metadata.has_next is true on any full page. The nested filters object takes the analytics tools' filters keys, except recipient_id, and wins per field over the flat ones. Failures are assistance_listings_type_mismatch (listings with a non-assistance group), psc_codes_type_mismatch (PSC codes with an assistance group), unsupported_sort, date_range_inverted, date_before_earliest, and invalid_location (an unknown state, a 3-digit county without a state, a county under an armed-forces code (AA/AE/AP), a county or FIPS-number state under another country, or parts naming different states)
• sort depends on the group: loans take Loan Value (default), Subsidy Cost, Issued Date, Recipient Name, or Awarding Agency; the others Award Amount (default), Total Outlays, Start Date, End Date (not IDVs), Recipient Name, or Awarding Agency. Page numbers stop at a 50,000-result offset (pagination_limit_exceeded); past it, page with the last_record_sort_value + last_record_unique_id cursor, returned below a 10,000-result offset
• Effective keywords need at least three characters, with whitespace preserved. NAICS codes use 2, 4, or 6 digits; recognized numeric aliases such as 054, +54, and 54_15_12 are normalized and echoed. Validation runs after nested-filter precedence, so an overridden flat value does not reject the call; active invalid values fail as invalid_keyword or invalid_naics_code

usaspending_get_award tool

• award_id is a generated_unique_award_id, the generated_internal_id from search; an unknown ID fails as award_not_found
• Returns category, total_obligation, total_outlays, total_account_obligation, total_account_outlay, base_exercised_options, subaward_count, NAICS / PSC codes, account_obligations_by_defc, account_outlays_by_defc, and, on loans, total_loan_value and total_subsidy_cost, where supplied
• assistance_listings lists every Assistance Listing on an assistance award, in upstream order, as number, title, and obligation; a number goes in usaspending_search_awards assistance_listings
• recipient carries uei, parent_uei, business_categories (category names, not the business_types codes of usaspending_get_recipient), and a three-letter country_code, county_name, congressional_code, and zip5 on its location. place_of_performance also carries a country code, county name, and congressional code; a location with no fields upstream is omitted
• recipient.recipient_id and recipient.parent_recipient_id chain to usaspending_get_recipient and parent_award.generated_unique_award_id to the parent IDV; category: "idv" awards list their children via usaspending_get_idv_awards

usaspending_get_award_transactions tool

• award_id plus sort (action_date, federal_action_obligation, modification_number); limit up to 100
• Rows carry a string id (ASST_TX or CONT_TX), action_date, modification_number, action_type, and a signed federal_action_obligation (negative is a deobligation). Loan transactions also carry face_value_loan_guarantee and original_loan_subsidy_cost; assistance transactions carry cfda_number when supplied

usaspending_get_award_subawards tool

• award_id plus sort (subaward_number, description, action_date, amount, recipient_name); limit up to 100
• Rows carry id, subaward_number, description, amount, action_date, and recipient_name; the upstream listing supplies no recipient UEI or location. subaward_count on usaspending_get_award says whether any exist

`usasp