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

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

Contributing

Please see the testing section as a starting point to test your changes before submitting a PR. If you are adding a new tool, please also add a copy of the respective contract used as a reference to create the inputSchema and outputSchema. Please add the tool to the same path that it exists in the usaspending_api contacts directory. For file naming convention refer to the contract file name and name the tool this as well. For example, if you are creating a tool for the v2/disaster/spending_by_geography.md API route this tool should be added with under the path tools/v2/disaster/spending_by_geography.py and the tool should be named disaster_spending_by_geography. Should there be any objections to this please explain why in the PR as it is not bullet proof!

License

This project is licensed under the MIT License - see the LICENSE file for details.