USA Spending MCP Server: Track Federal Spending

Overview

The USA Spending MCP Server is an implementation of the Model Context Protocol (MCP) built around USASpending.gov data. It offers a programmatic way to search federal agencies, inspect awards and recipients, and surface community-level spending trends that can be consumed by retrieval-augmented models, search UIs, or analytics pipelines.

By combining structured USASpending data with MCP-style endpoints, the server helps developers provide LLMs and other agents with concise, relevant context about federal spending. Typical uses include building conversational assistants that answer queries about agency budgets, exploring geographic impact (county/ZIP-level awards), and tracking spending changes over time.

Features

• Exposes MCP-compatible endpoints to return context fragments and documents for LLM retrieval.
• Indexes and serves USASpending.gov datasets: agencies, awards, recipients, and award totals by geography/time.
• Search and filter across agencies, award types, time ranges, and geographies.
• Support for paginated, structured results suitable for embedding or prompt augmentation.
• Lightweight deployment via Docker or local runtime for development.
• Integrates with external vector stores or caches for higher-performance retrieval (optional).

Installation / Configuration

Clone the repository and choose a deployment path: Docker (recommended) or local runtime. Replace values shown with your environment-specific settings.

Clone repo:

git clone https://github.com/thsmale/usaspending-mcp-server.git
cd usaspending-mcp-server

Docker (quick start):

docker build -t usaspending-mcp-server .
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e USASPENDING_API_URL=https://api.usaspending.gov \
  -e CACHE_DIR=/var/cache/usaspending \
  --name usaspending-mcp-server \
  usaspending-mcp-server

Local (Node / Python — check project README for language-specific commands):

# Example for Node.js projects
npm install
export PORT=8080
export USASPENDING_API_URL="https://api.usaspending.gov"
npm start

# Example for Python projects
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export PORT=8080
export USASPENDING_API_URL="https://api.usaspending.gov"
python app.py

Common environment variables

• PORT: HTTP port to listen on (default: 8080).
• USASPENDING_API_URL: Base URL for USASpending API (default: https://api.usaspending.gov).
• CACHE_DIR: Path to local cache or data store for downloaded datasets.
• DATABASE_URL: Optional connection string for a backing relational DB.
• LOG_LEVEL: Info/Debug/Error for server logs.

Always consult the repository’s README and example .env file for exact variables and optional integrations (vector DB, authentication, etc).

Available Resources

The server exposes HTTP endpoints that align with MCP usage patterns. Check the repo for exact routes and request/response schemas. Typical resources include:

Example curl call to search agencies:

curl -X GET "http://localhost:8080/agencies?query=air%20force&limit=10"

Example MCP query (simplified):

curl -X POST "http://localhost:8080/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "How much did the Department of Transportation spend on infrastructure in 2022?",
    "filters": { "agency_id": 69, "fiscal_year": 2022 }
  }'

Response objects are structured to be machine-readable and easily appended as context to LLM prompts (title, summary, source, timestamp, link).

Use Cases

• Build a conversational assistant: Supply LLMs with precise spending context (agency budgets, recent awards) so answers cite real federal data rather than hallucinating amounts.
  • Example: User asks “How much did NOAA receive for coastal resilience in 2021?” The app POSTs a filtered MCP query for NOAA + category + year and formats the returned fragments into the assistant’s prompt.
• Geographic impact reporting: Aggregate award totals by county or ZIP code to see local community benefits.
  • Example: Call /geography?zip=02139&start_year=2018&end_year=2023 to retrieve award totals and major recipients that served a given ZIP.
• Trend and time-series analysis: Fetch award totals across fiscal years to plot spending growth/decline for an agency or program.
  • Example: Use /awards with fiscal_year range and aggregate by year to produce a CSV for visualization.
• Searchable dataset for researchers: Expose agency, award, and recipient metadata to internal search tools or knowledge bases; integrate with vector stores to power semantic search.

Tips for Developers

• Validate the server’s MCP responses against your model’s prompt size/formatting needs—trim or prioritize fragments to stay within token limits.
• Use caching (CACHE_DIR or a DB) for expensive USASpending API calls; public datasets can be large and rate-limited.
• When integrating with LLMs, include source links and timestamps in returned fragments so answers can reference provenance.
• Inspect the repository’s tests and example clients to understand exact request/response shapes before production integration.

Useful links

• Repository: https://github.com/thsmale/usaspending-mcp-server
• USASpending API docs: https://www.usaspending.gov/api-documentation
• Model Context Protocol (MCP): check the repo for the server’s MCP schema and examples

This MCP server turns authoritative public spending data into consumable context for search, analysis, and AI-powered workflows. Check the GitHub repo for the latest installation instructions, API schema, and example integrations.