Query USASPENDING.gov Data via HTTP
USA Spending MCP Server lets AI assistants query USASpending.gov data - agency budgets, recipients, awards, and spending trends.
Why it matters
Access and analyze comprehensive US federal spending data through a stateless, streamable HTTP MCP server. Explore spending trends, agency allocations, and community investments.
Outcomes
What it gets done
Retrieve federal account details and budgetary resources.
Analyze spending patterns by agency, recipient, and time.
Filter and visualize subaward and spending data.
Track government spending over time and by agency.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/vb-usa-spending-mcp-server | bash Capabilities
Tools your agent gets
Returns a list of federal accounts, their numbers, names, managing agencies, and budgetary resources
Retrieves a list of all budget functions, sorted by name
Understand the various ways a specific agency spends money
Visualizes government spending related to a specific recipient
Details specific subsets of data at the level of granularity representing all government spending
Allows comprehensive filtering for specific subsets of spending data with filters and fields
Returns aggregated award amounts grouped by time periods in ascending order
Returns a filtered set of subcontracts
Overview
USA Spending MCP Server
USA Spending MCP Server wraps the USASpending.gov API so an AI assistant can query real federal spending data directly - agency budgets, recipients, awards, subawards, and spending trends over time. Use it for research or transparency questions specifically about U.S. federal government spending; it is read-only and does not cover state, local, or non-U.S. spending data.
What it does
USA Spending MCP Server is a stateless, streamable HTTP MCP server that wraps the USASpending.gov API, the official source of U.S. federal government spending data. It lets an AI assistant track spending over time, search by agency, look at how money flows to specific recipients and communities, and drill into individual awards and subawards - all backed by the same data as the USASpending.gov dashboard.
When to use - and when NOT to
Use this connector when you want an assistant to answer questions grounded in real federal spending data: how an agency spends its budget, who received federal awards or contracts, how spending in a category or region has changed over time, or details on a specific award or subaward. It's built for research and transparency questions about U.S. federal spending specifically. It is not useful for state, local, or non-U.S. government spending, and it does not modify anything - it's a read-only wrapper over the public USASpending.gov API.
Capabilities
federal_accounts: shows how agencies receive and spend congressional funding across programs and activities.list_budget_functions: lists all Budget Functions ordered by title.major_object_class: shows the different ways a specific agency spends money.recipient: lists recipients of government funding with level, DUNS, UEI, and amount.spending: drills into spending for a time period, grouped by a chosen data type.spending_by_award: filters award data by fields and criteria, e.g. largest awards in a given year.spending_over_time: returns aggregated award amounts by time period, earliest to most recent.subawards: returns a filtered set of subawards.total_budgetary_resources: reports federal budgetary resources, e.g. total budget by year.toptier_agencies: shows which agencies receive the most money.
Each tool maps to a corresponding route in the usaspending-api's own API contracts, documented per-tool for reference.
How to install
Run locally with uv:
uv run src/server.py
Or install from PyPI:
uvx --from usaspending-mcp-server@latest usaspending-mcp-server
Or build and run with Docker:
docker build -t usaspending-mcp-server .
docker run -p 8000:8000 usaspending-mcp-server
For Claude Desktop, add an mcpServers entry using mcp-remote pointed at the running server, e.g. command: npx, args ["mcp-remote", "http://localhost:8000/mcp"]. The host and port can be customized via MCP_SERVER_HOST and MCP_SERVER_PORT.
Who it's for
Journalists, researchers, policy analysts, and civic-tech developers who want an AI assistant to answer questions about U.S. federal spending directly from USASpending.gov data, without manually navigating the dashboard or API docs.
Source README
USA Spending MCP Server
This is a stateless streamable HTTP MCP server for interacting with USASPENDING.gov, the official source of government spending data.
You can track government spending over time, search government spending by agency, explore government spending to communities, and much more.
USASPENDING.gov provides this neat dashboard which shows some of the powers of the API should you want a high level overview of what you can achieve with this API.
The API docs can be viewed at this URL.
Running Locally
uv run src/server.py
Running from PyPi
uvx --from usaspending-mcp-server@latest usaspending-mcp-server
Running from Docker
docker build -t usaspending-mcp-server .
docker run -p 8000:8000 usaspending-mcp-server
Using with Claude Desktop
Update your claude_desktop_config.json with the following configuration.
Ensure the MCP server is running by using one of the methods mentioned above.
{
"mcpServers": {
"usaspending": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8000/mcp"
]
}
}
}
Configuration Options
The following env or .env variables are accepted to customize what host and port the MCP server runs on.
MCP_SERVER_HOST
MCP_SERVER_PORT
Tools
| Name | Description | Example prompts |
|---|---|---|
| federal_accounts | Use this tool to get a better understanding of how agencies receive and spend congressional funding to carry out their programs, projects, and activities. | - Provide specifics on how the Department of Homeland Security spends money. |
| list_budget_functions | This retrieves a list of all Budget Functions ordered by their title | - How much does the government spend on community and regional development versus international affairs? |
| major_object_class | This data can be used to better understand the different ways that a specific agency spends money | - How much money does the Department of Education spend on employee pay and benefits? |
| recipient | This can be used to visualize the government spending that pertains to a specific recipient. This returns a list of recipients, their level, DUNS, UEI, and amount. | - What are some companies that received funding from the NSA? |
| spending | This data can be used to drill down into specific subsets of data by level of detail. This data represents all government spending in the specified time period, grouped by the data type of your choice. | - Provide spending by agency for General Science, Space, and Technology. |
| spending_by_award | This allows for complex filtering for specific subsets of spending data. This accepts filters and fields, and returns the fields of the filtered awards. | - What was the largest award in 2025? - What are some companies that received major federal contracts in Lindsey Graham's district? |
| spending_over_time | This returns a list of aggregated award amounts grouped by time period in ascending order (earliest to most recent). | - How has spending changed to California over the last 5 years? |
| subawards | This returns a filtered set of subawards | - Describe some of the subawards for CONT_AWD_FA870221C0001_9700_-NONE-_-NONE- and provide a rationale for them. |
| total_budgetary_resources | This is used to provide information on the federal budgetary resources of the government | - What was the government budget in 2025 vs 2024? - How much money does the federal government provide in total to various government agencies? |
| toptier_agencies | This data can be used to better understand the different ways that a specific agency spends money | - Which federal agency receives the most money? |
tools directory explained
As each tool is basically a wrapper for an API route, each tool is mapped similarly to the directory structure in the api_contracts directory of the usaspending-api.
However, for tools federal_accounts, recipient, spending, and subawards their API mapping are the contracts mentioned in the root directory api_contracts/v2.
There is a md file for each tool so it is convenient to reference the documentation used to create the tool.
These contracts are rarely updated in the usaspending-api, but checks should still be performed to ensure they are up to date.
Currently, all contracts (aka API documentation) are referenced from commit dv551d0 of the usaspending-api.
Testing
MCP Inspector is a good way to test the input and output schema without connecting to a LLM.
There is also a sample MCP Client to test the application using OpenAI.
There are also a variety of unit tests focusing on the tool handlers, input/output schemas, and HTTP calls to the USASpending API.
They can be run with the following command.
uv run pytest
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.