beholder-mcp

An MCP server for the Beholder government contracting API, built with FastMCP and Python.

Beholder aggregates and enriches data from SAM.gov and USASpending.gov, providing higher rate limits and richer analysis than either public API — including risk indicators, contract vehicles, competition metrics, and subaward tracking.

Prerequisites

• uv
• A Beholder API key — get one at api.beholder-gov.com/docs

Setup

git clone https://github.com/rsivilli/beholder-mcp
cd beholder-mcp

Create a .env file and set your API key:

BEHOLDER_API_KEY=your_api_key_here

Running the server

stdio (for MCP clients that spawn the process, e.g. Claude Desktop):

uv run beholder-mcp

HTTP (for connecting remotely):

uv run beholder-mcp-http

Claude Desktop configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "beholder": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/beholder-mcp", "beholder-mcp"],
      "env": {
        "BEHOLDER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available tools

Contractors

Opportunities

Contracts & subawards

Development

Install dev dependencies and set up pre-commit hooks:

uv sync
uv run pre-commit install

Run linting and formatting checks:

uv run pre-commit run --all-files