birre

boecht/birre

3.2

If you are the rightful owner of birre and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server providing access to BitSight security rating data using FastMCP and the brandon-smith-187/bitsight Python library.

Tools
2
Resources
0
Prompts
0

BiRRe (Bitsight Rating Retriever) is a Model Context Protocol (MCP) server that provides access to BitSight security rating data through an existing subscription. It utilizes FastMCP for API integration with BitSight and can be run easily without installation in a temporary, isolated Python environment with uv.

Installation

Quick start

  • Set your BitSight API key, then start BiRRe:
export BITSIGHT_API_KEY="your-bitsight-api-key"
uvx --from git+https://github.com/boecht/birre server.py
  • Point your LLM of choice to the MCP server and ask it for the BitSight rating of any company.

Configuration

Configuration sources (lowest → highest): config.toml → config.local.toml → environment → CLI. See the header in config.toml for available fields and details. For CLI options, run with --help.

Run directly from GitHub with uvx

uvx --from git+https://github.com/boecht/birre server.py

Or run locally

git clone https://github.com/boecht/birre
uv run server.py

That's it! The script will automatically install all dependencies using uv.

Alternatively run with fastmcp for more options, like HTTP transport.

Disclaimer

BiRRe (Bitsight Rating Retriever) is not affiliated with, endorsed by, or sponsored by BitSight Technologies, Inc. This is an unofficial, community-developed MCP server that provides integration with Bitsight's publicly available services.

  • This project is developed and maintained independently by the open source community
  • "Bitsight" is a registered trademark of BitSight Technologies, Inc.
  • This integration is provided "as-is" without any warranty or official support from BitSight Technologies, Inc.

This project enables third-party access to Bitsight services through their public APIs and is intended for educational and integration purposes only.

Features

Available Tools

BiRRe now supports context-specific toolsets:

  • standard context (default) – quick rating workflows
    • company_search: Search BitSight for companies by name or domain
    • get_company_rating: Retrieve security ratings with automatic subscription management
  • risk_manager context – subscription and onboarding operations
    • company_search_interactive: Enriched search results (name + GUID, domains, description, employee count, subscription folders) for human-in-the-loop selection
    • manage_subscriptions: Bulk subscribe/unsubscribe GUIDs with dry-run support and audit summaries
    • request_company: Submit BitSight company requests (deduplicates existing requests, attempts v2 bulk workflow with folder targeting, falls back gracefully)
    • company_search and get_company_rating remain available for spot checks

Select a context via --context, BIRRE_CONTEXT, or the [runtime].context config key. Invalid values default to standard with a warning.

BitSight API Documentation (v1 + v2 are complementary)

API Version: This implementation is based on BitSight APIs as of July 24th, 2025. For the latest API changes and updates, refer to the BitSight API Change Log.

Interactive API Documentation (requires BitSight account login):

Schema Updates: To update API schemas when forking or contributing:

  1. Log into BitSight web interface
  2. Download schemas from:
  3. Save as apis/bitsight.v1.schema.json and apis/bitsight.v2.schema.json

Version History and Outlook

Version 1.0: MVP

  • Company Search: Search for companies by name or domain via BitSight v1 companySearch
  • Company Rating: Retrieve core rating details with automatic subscription management
  • Ephemeral Subscriptions: Subscribe/unsubscribe on demand to avoid license leakage
  • Structured Error Handling: Clear responses for quota/subscription failures
  • uv/uvx Compatible: Run easily with uv using PEP 723 inline script metadata

Version 2.0: Top Vulnerability Insights (Current)

  • Top Findings Summary: Attach the most impactful vulnerabilities to the rating payload, using relaxed severity filters (severe/material first, then moderate with web-appsec padding when needed)
  • Enhanced Sorting: Prioritise findings by severity, asset importance, and recency to keep the worst issues on top
  • Narrative Improvements: Normalise detection/remediation text for quick consumption by MCP clients
  • Configuration Hooks: Continue to rely on v1 findings endpoints while keeping v2 tooling optional via BIRRE_ENABLE_V2

Version 3.0: Context Modes (Current)

  • Two personas: standard (quick ratings) and risk_manager (subscription operations)
  • Context-driven tool filtering via CLI (--context), env (BIRRE_CONTEXT), or config
  • Risk manager tooling delivers enriched search data, dry-run batch subscription workflows, and company onboarding requests without in-tool prompts (LLMs coordinate user confirmations)
  • Optional BitSight v2 bridge loads automatically when the risk manager context is active

Version 4.0: Caching Layer (Not Implemented)

  • Daily caching of ratings and reusable storage for PDF artifacts
  • Reduce duplicate API calls and avoid re-downloading recent reports

Version 5.0: Company Reports (Not Implemented)

  • Download official PDF reports
  • Deliver via direct attachment, email, or configured file share (POSIX path or SharePoint)

Version 6.0: Multi-Tenant Service (Not Implemented)

  • Remote deployment support
  • Authentication and authorization
  • Concurrent user support

Testing

BiRRe ships with both offline unit tests and opt-in live integration checks. The offline suite exercises configuration layering, logging formatters, startup checks, subscription helpers, and both standard and risk-manager tools without touching the BitSight API. The live tests drive the FastMCP client end-to-end against BitSight and require real credentials.

# Run the offline suite (no network calls).
uv run pytest -m "not live"

# Run the live smoke tests against BitSight.
uv run pytest -m live -rs

Live tests require a valid BITSIGHT_API_KEY in the environment (or config.local.toml) and the fastmcp client dependency, which uv run will install on demand inside an isolated virtual environment.