beholder-mcp 1.0.0

MCP server for the Beholder government contracting API

beholder-mcp

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

Beholder provides richer data and higher rate limits than SAM.gov — including risk indicators, contract vehicles, subaward tracking, and more.

Prerequisites

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

Setup

git clone https://github.com/rsivilli/beholder-mcp
cd sam-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

Tool	Description
search_contractors	Search contractors by name, UEI, state, or agency — returns paginated list with obligation totals and review priority scores
get_contractor	Get a contractor record by UEI or name — returns full profile with top agencies, PSC codes, vehicle summaries, and risk indicators
resolve_contractor	Resolve a company name or UEI to its Beholder UUID and key fields — returns the single best match
get_contractor_profile	Full contractor profile in one call: registration details, recent contracts, risk indicators, and contract vehicles
find_competitors	Find contractors competing in the same PSC code categories as a given company

Opportunities

Tool	Description
search_opportunities	Search contract opportunities and award notices by keyword, NAICS code, set-aside, agency, active status, and date filters

Contracts & subawards

Tool	Description
search_contracts	Search awarded contracts by PIID prefix, recipient, PSC code, fiscal year, obligation range, date range, status, and award type
get_related_contracts	Given a contract PIID, find related contracts — parent, siblings, same vehicle, or same awardee
search_subawards	Get subaward reports filed under a specific prime contract PIID

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