Skip to main content
Glama
USA Spending MCP Server

USA Spending MCP Server

Official
by GSA-TTS

USA Spending MCP Server

⚠️ DISCLAIMER: This is a proof of concept and is not intended for production use.

An MCP server for interacting with the USAspending.gov API, with optional login.gov authentication for cloud deployment.

Requirements

  • Python 3.11+

  • uv

Related MCP server: federal-compass-mcp

Installation

Quick Install

uv tool install git+https://github.com/GSA-TTS/usa-spending-mcp-server

Development Setup

git clone https://github.com/GSA-TTS/usa-spending-mcp-server
cd usa-spending-mcp-server
uv sync --dev

Running Modes

The server supports two modes:

Mode

Command

Use Case

stdio

usa-spending-mcp-server

Local use with Claude Desktop

HTTP

usa-spending-mcp-server-http

Cloud deployment with login.gov auth

Local Setup (Claude Desktop)

  1. Get the installed tool path:

    which usa-spending-mcp-server
  2. Add to your Claude MCP config (~/.claude/claude_desktop_config.json):

    {
      "mcpServers": {
        "usa-spending": {
          "command": "/path/to/usa-spending-mcp-server"
        }
      }
    }

HTTP Server with Login.gov Authentication

The HTTP server uses login.gov OIDC with PKCE for authentication, suitable for cloud.gov deployment.

Environment Variables

Variable

Required

Description

REQUIRE_AUTH

No

Set to "false" to disable auth (default: "true")

BASE_URL

If auth enabled

Public URL of the server (e.g., https://usa-spending-mcp.app.cloud.gov)

LOGINGOV_CLIENT_ID

If auth enabled

Your login.gov application client ID

JWT_SIGNING_KEY

If auth enabled

Secret key for signing JWTs (generate with python -c "import secrets; print(secrets.token_hex(32))")

LOGINGOV_CONFIG_URL

No

OIDC discovery URL (defaults to login.gov sandbox)

PORT

No

Server port (default: 8080)

Login.gov Setup

  1. Register at partners.login.gov

  2. Create a new OIDC application:

    • Protocol: OpenID Connect with PKCE (public client)

    • Redirect URI: {BASE_URL}/auth/callback

  3. Note your client ID for LOGINGOV_CLIENT_ID

Running Locally

Without authentication (development):

uv run task dev

With authentication:

export BASE_URL=http://localhost:8080
export LOGINGOV_CLIENT_ID=your-client-id
export JWT_SIGNING_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
uv run task dev-auth

Cloud.gov Deployment

  1. Set environment variables:

    cf set-env usa-spending-mcp-server BASE_URL https://usa-spending-mcp.app.cloud.gov
    cf set-env usa-spending-mcp-server LOGINGOV_CLIENT_ID your-client-id
    cf set-env usa-spending-mcp-server JWT_SIGNING_KEY your-signing-key
  2. Deploy:

    cf push

Development

Available Tasks

uv run task dev          # Run HTTP server without auth
uv run task dev-auth     # Run HTTP server with auth
uv run task lint         # Check code with ruff
uv run task lint-fix     # Fix linting issues
uv run task format       # Format code with ruff
uv run task test         # Run tests
uv run task test-cov     # Run tests with coverage
uv run task ci           # Run all CI checks

Code Quality

This project uses ruff for linting and formatting.

LLM-Based Evals (Optional)

For local testing of tool behavior using mcp-evals:

cd evals
npm install
ANTHROPIC_API_KEY=your-key npm run eval

See evals/README.md for details.

Project Structure

src/
  usa_spending_mcp_server/
    server.py        # stdio MCP server (Claude Desktop)
    server_http.py   # HTTP server with auth (cloud.gov)
    auth.py          # login.gov OIDC authentication
tests/               # Python unit tests
evals/               # LLM-based evals (optional)
manifest.yml         # cloud.gov deployment config
pyproject.toml

Available Tools

3 tools
executeB

Chain await call_tool(...) calls in one Python block; prefer returning the final answer from a single block. Use return to produce output. Only call_tool(tool_name: str, params: dict) -> Any is available in scope.

Inputs: code (required).

get_schemaA

Get parameter schemas for specific tools.

Use after searching to get the detail needed to call a tool.

Inputs: tools (required), detail. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools (execute, get_schema, search) have clearly distinct purposes: search finds tools, get_schema retrieves parameter details, and execute runs tools. No overlap.

    Naming Consistency4/5

    All tools use lowercase verbs, which is consistent. However, the pattern varies: 'execute' is a standalone verb, while 'get_schema' and 'search' combine verb and noun. Minor deviation from a strict pattern.

    Tool Count1/5

    With only 3 generic meta-tools and no domain-specific tools for USA Spending, the tool count is extremely insufficient for the server's purported purpose. It should have at least basic query tools for spending data.

    Completeness1/5

    The server claims to be about USA Spending but provides no tools to access spending data. The entire domain surface is missing, making it severely incomplete.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      MCP server for integrating Actual Budget with Claude and other LLM assistants.
      17
      494 npm
      287
      TypeScript
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that connects Claude to the USAJobs API, enabling natural language search for federal jobs, translation of government jargon, CV qualification analysis, and explanation of federal concepts like GS grades and clearances.
      10
      73 npm
      12
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for exploring US federal spending data via the USAspending.gov API, enabling natural language queries on awards, agencies, recipients, and spending trends.
      12
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A free, key-less MCP server for querying U.S. federal spending data from USAspending.gov, including contracts, grants, loans, recipients, agencies, and geographic breakdowns.
      MIT