boecht/birre
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 dayong@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.
BiRRe
BiRRe (Bitsight Rating Retriever) is a Model Context Protocol (MCP) server that turns a BitSight subscription into LLM-friendly tools. It hides 400+ raw endpoints behind a curated, strongly-typed workflow surface, handles ephemeral subscriptions automatically, and ships as a zero-install uv app so analysts and agents can run it anywhere.
Why use BiRRe?
- Unified workflows – LLMs gain one consistent toolset for search, ratings, onboarding, and subscription hygiene.
- Safer operations – automatic folder targeting, dry-run previews, and retry-aware helpers keep BitSight data tidy while preventing accidental churn.
- Trustworthy releases – strict typing (pyright), property-based tests, signed artifacts, and SBOMs make it easy to depend on BiRRe in regulated environments.
What you need
| Requirement | Details |
|---|---|
| BitSight access | API key with rights to the companies/folders you intend to query. |
| Runtime | Python 3.13+ (uv auto-installs across Linux/macOS/Windows). |
| Network | HTTPS to api.bitsighttech.com for live data; custom CAs are supported. |
| Client | Any MCP-compatible LLM or agent platform (GPTs, LangChain, local MCP clients, etc.). |
Quick start
-
Export your BitSight API key.
-
Start the MCP server with uvx (install-free PyPI run):
export BITSIGHT_API_KEY="your-bitsight-api-key" uvx birre -
Point your MCP-compatible client/LLM at the server endpoint. Start with
company_searchto obtain GUIDs, then callget_company_ratingor run the risk-manager workflows. -
Use
--helpfor every available command, subcommand, and option.
The rest of this README assumes a local checkout:
Create a local copy with git clone https://github.com/boecht/birre,
then start with uv run birre in the BiRRe directory.
Configuration
Configuration layers merge in this order: config.toml → config.local.toml → environment variables →
CLI flags. Inspect or validate the effective settings with:
uv run birre config show
uv run birre config validate --config differently/named/config.toml
See for full option tables and for annotated defaults.
Tooling overview
Switch contexts via --context, BIRRE_CONTEXT, or [runtime].context. Tool names map directly to MCP tool calls.
Shared tools (standard + risk_manager)
| Tool | Inputs | Description |
|---|---|---|
company_search | Company name (fuzzy) or domain (exact). | Returns the matches (GUID, name, domain, count of eligible companies). |
get_company_rating | Company GUID. | Compiles a rating payload: current value/color, 8‑week and 1‑year trends, prioritized findings, and the rating legend. (automatically subscribes and unsubscribes, if needed) |
risk_manager-only tools
| Tool | Inputs | Description |
|---|---|---|
company_search_interactive | name or domain (same as company_search). | Enriches search result with current rating, number of employees, subscription state, and more) plus the same info about the parent company. |
manage_subscriptions | action (add/delete), list of GUIDs, optional folder, dry_run. | Validates intent, resolves/creates folders for adds, then executes subscription changes. Returns either a dry-run preview or applied summary (added/deleted/errors, folder metadata). |
request_company | Comma-separated domains (max 255), optional folder, dry_run. | Deduplicates submissions, reports already-requested domains, and submits BitSight bulk onboarding CSVs when available (legacy fallback otherwise). Includes a per-domain success/failure summary and folder info. |
Self-test
Use the built-in self test to sanity-check your setup before connecting a
client. The command mirrors the run startup sequence, reports the resolved
configuration, and exercises BitSight connectivity, subscription, and tooling
checks against BitSight’s testing environment (staging). When invoked with
--offline, only the local configuration and logging checks run.
# Run the full diagnostics against the default BitSight testing endpoint.
uv run birre selftest
# Target the production API to exercise real subscription logic and permissions.
uv run birre selftest --production
Successful runs exit with 0. Failures return 1, and partial results with
warnings (for example, optional tooling gaps in offline mode) return 2.
Expect occasional 403 Access Denied responses when using BitSight’s testing
environment.
Documentation, support & contributions
- – full command reference, configuration helpers, option tables.
- – current release summary plus upcoming milestones.
- – FastMCP layering and BitSight integration design.
- – verifying signed releases (Sigstore, SBOM, PyPI).
- – curated BitSight endpoint overviews (v1/v2).
- – development workflow, pytest/pyright instructions, PR expectations.
- – reporting process and supported-release policy.
Issues and PRs are welcome; contributions are released under the .
Disclaimer
BiRRe (Bitsight Rating Retriever) is not affiliated with, endorsed by, or sponsored by BitSight Technologies, Inc.
- 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.
- Use is intended for integration scenarios respecting BitSight’s terms.