BitSight Community MCP Server

<div align="center"> <img src="birre-logo.png" alt="Birre Logo" width="375"> </div> A Model Context Protocol (MCP) server that provides access to BitSight security rating data. It utilizes [FastMCP](https://gofastmcp.com/) and the [brandon-smith-187/bitsight](https://github.com/brandon-smith-187/bitsight) Python library. It can be run easily without installation in a temporary, isolated Python environment with uv. ## Installation ### Configuration Set these environment variables: - `BST_API_KEY` (required): Your BitSight API key - `DEBUG` (optional): Enable debug logging (`true`, `false`, default: `false`) ```bash export BST_API_KEY="your-bitsight-api-key" ``` ### Run directly from GitHub with uvx ```bash uvx --from git+https://github.com/boecht/birre server.py ``` ### Or run locally ```bash git clone https://github.com/boecht/birre uv run server.py ``` That's it! The script will automatically install all dependencies using PEP 723 inline metadata. Alternatively run with `fastmcp` for more options, like **HTTP transport**. ## Disclaimer This project 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 ### Version 1.0 (MVP) - **Company Search**: Search for companies by name or domain - **Company Rating**: Get security ratings with automatic subscription management - **Ephemeral Subscriptions**: Automatically subscribe and unsubscribe for one-time rating requests - **Structured Error Handling**: Clear error responses for API issues and quota limits - **uv/uvx Compatible**: Run easily with uv using PEP 723 inline script metadata ### Available Tools #### company_search Search for companies in the BitSight database. **Parameters:** - `name` (optional): Company name to search for - `domain` (optional): Company domain to search for **Returns:** - `companies`: List of matching companies with `GUID`, `name`, `domain`, and `industry` - `count`: Total number of matches - `search_term`: The term used for searching **Example:** ```json { "companies": [ { "guid": "e90b389b-0b7e-4722-9411-97d81c8e2bc6", "name": "GitHub, Inc.", "domain": "github.com", "industry": "Technology" }, ... ], "count": 4, "search_term": "GitHub" } ``` #### get_company_rating Get security rating for a company by GUID. Automatically manages BitSight subscriptions. **Parameters:** - `guid` (required): BitSight GUID of the company **Returns:** - `rating`: Current security rating (0-900 scale) - `rating_date`: Date of the rating - `grade`: Letter grade (A, B, C, D, F) - `company_name`: Name of the company - `auto_subscribed`: Boolean indicating if auto-subscription was performed - `auto_unsubscribed`: Boolean indicating if auto-unsubscription was performed **Example:** ```json { "rating": 740, "rating_date": "2025-08-26", "grade": "A", "company_name": "GitHub, Inc.", "auto_subscribed": true, "auto_unsubscribed": true } ``` ## Development ### Project Structure ``` birre/ ├── server.py # PEP 723 entry point script ├── src/ │ └── birre/ │ ├── __init__.py │ ├── server.py # Main FastMCP server │ ├── config.py # Configuration management │ └── tools/ │ ├── __init__.py │ ├── company_search.py │ └── company_rating.py ├── tests/ │ ├── unit/ # Unit tests with mocked dependencies │ └── integration/ # Integration tests with real API calls └── requirements.txt # Development dependencies ``` ## Future Versions ### Version 2.0: Category Risk Ratings - Retrieve risk ratings by category/vector - Filter by specific risk categories ### Version 3.0: Company Reports - Download official BitSight PDF reports - Handle report generation limits ### Version 4.0: Database Caching - Daily caching of company rating data - Reduce duplicate API calls ### Version 5.0: Multi-Tenant Service - Remote deployment support - Authentication and authorization - Concurrent user support ## License This project is licensed under the MIT License.