usaspending

This MCP server provides a stateless, streamable HTTP interface to USAspending data. It exposes a set of Tools that wrap specific USASPENDING API endpoints and contracts, allowing you to query spending details, agency budgets, recipients, and other federal spending data in a structured, prompt-driven way. The server is designed to be lightweight and scalable, enabling you to run it locally or in a container and connect your MCP clients or Claude Desktop integrations to the /mcp endpoint.

To use it, start the server using the installation method of your choice (via uvx from PyPI in a Python environment, or by running the Python script locally). Once running, you can issue prompts to invoke any of the available tools, such as federal_accounts, recipient, spending, spending_by_award, and more. The tools act as API wrappers that translate natural language prompts into API requests to the USASPENDING.gov backend, returning structured results that you can feed into downstream workflows, dashboards, or LLM-assisted analyses.

Prerequisites:

• Python 3.8+ installed on your machine
• Access to install Python packages (pip, or pipx)

Option A: Run locally with uv (Python script)

1. Ensure Python is installed and up to date.
2. Install uv (if not already installed) and dependencies:
   • pip install uvicorn # if you plan to run a uvicorn-based app locally
   • pip install uvx # optional if you want to use uvx directly
3. Run the server (from repository root):
   • uv run src/server.py # per the README example
4. The server should be available at the host/port indicated by its configuration (default 8000).

Option B: Run via uvx (recommended with PyPI)

1. Ensure Python is installed.
2. Install uvx from PyPI:
   • pip install uvx OR pipx install uvx
3. Start the MCP server from PyPI package:
   • uvx --from usaspending-mcp-server@latest usaspending-mcp-server
4. The server will start and listen on the configured host/port (default 8000).

Option C: Docker (alternative)

1. Build and run the image as shown in the README:
   • docker build -t usaspending-mcp-server .
   • docker run -p 8000:8000 usaspending-mcp-server
2. Access the MCP endpoint at http://localhost:8000/mcp when running in Docker.

Environment variables you may encounter or customize include MCP_SERVER_HOST and MCP_SERVER_PORT to change where the MCP server binds. The Tools listed (e.g., federal_accounts, recipient, spending, spending_by_award, total_budgetary_resources, toptier_agencies) map to USASPENDING API routes via contracts. If you plan to add new tools, mirror the USASPENDING API contracts under the appropriate tools path and ensure input/output schemas are updated. When using Claude Desktop, configure it to point to the /mcp endpoint and ensure the server is running prior to testing. If you encounter connectivity issues, verify port mappings (e.g., 8000) and that the correct host is used in your client configuration.