Skip to main content
Glama

BBOT MCP Server

by marlinkcyber

BBOT MCP Server

A Model Context Protocol (MCP) server for running BBOT security scans. This server provides tools to manage and execute bbot scans through the MCP interface.

Features

  • Module Management: List and explore available bbot modules
  • Preset Management: List and use predefined scan configurations
  • Scan Execution: Start and manage long-running bbot scans
  • Real-time Monitoring: Check scan status and retrieve results
  • Wait & Progress Tracking: Wait for scan completion with timeout and progress reporting
  • Concurrent Scans: Support for multiple simultaneous scans
  • Dependency Management: Comprehensive sudo prevention and no-deps functionality

Installation

pip install bbot-mcp

From Source

git clone https://github.com/marlinkcyber/bbot-mcp.git cd bbot-mcp pip install -e .

Using uvx (Run without installing)

uvx bbot-mcp

Install dependencies

It is recommended to install all BBOT dependencies before invoking BBOT MCP server:

bbot --install-all-deps

Usage

Running the MCP Server

After installation, the server can be started using the bbot-mcp command:

bbot-mcp

Or directly with Python:

python -m bbot_mcp.server

Available Tools

The MCP server provides 8 tools for comprehensive bbot scan management:

1. list_bbot_modules()

Lists all available bbot modules categorized by type (scan, output, internal).

2. list_bbot_presets()

Lists all available bbot presets for quick scan configuration.

3. start_bbot_scan(targets, modules="", presets="", flags="", no_deps=True)

Starts a new bbot scan with the specified parameters.

Parameters:

  • targets: Comma-separated list of targets (domains, IPs, URLs)
  • modules: Optional comma-separated list of modules to use
  • presets: Optional comma-separated list of presets to apply
  • flags: Optional comma-separated list of flags
  • no_deps: Disable dependency installation to prevent sudo prompts (default: True)

Example:

start_bbot_scan("example.com,google.com", "httpx,nmap", "web-basic", "safe", True)

Important: The no_deps=True parameter prevents bbot from attempting to install missing dependencies, which would cause sudo password prompts that hang the MCP server.

4. get_scan_status(scan_id)

Retrieves the current status of a specific scan.

5. get_scan_results(scan_id, limit=100)

Retrieves results from a completed or running scan.

Parameters:

  • scan_id: The unique identifier of the scan
  • limit: Maximum number of results to return (default: 100)
6. list_active_scans()

Lists all currently active scans with their basic information.

7. wait_for_scan_completion(scan_id, timeout=300, poll_interval=5, include_progress=True)

Waits for a scan to complete with timeout and progress reporting.

Parameters:

  • scan_id: The ID of the scan to wait for
  • timeout: Maximum time to wait in seconds (default: 300 = 5 minutes)
  • poll_interval: How often to check scan status in seconds (default: 5)
  • include_progress: Whether to include progress updates in the response (default: True)

Returns:

  • Success response with completion details, elapsed time, and progress updates
  • Timeout response if scan doesn't complete within the specified time
  • Error response for invalid scan IDs or other issues

Example:

# Wait for scan to complete with custom timeout result = wait_for_scan_completion("scan-123", timeout=600, poll_interval=10)
8. get_dependency_info()

Provides information about bbot's dependency management system and how the MCP server handles dependencies.

MCP config example:

{ "mcpServers": { "bbot": { "command": "uvx", "args": ["--refresh","bbot-mcp"] } } }

Scan Management

Scan Lifecycle

  1. Starting: Scan is being initialized
  2. Running: Scan is actively executing
  3. Completed: Scan finished successfully
  4. Error: Scan encountered an error

Long-running Scans

Scans run in separate threads to avoid blocking the MCP server. You can:

  • Start multiple scans concurrently
  • Check status while scans are running
  • Retrieve partial results from ongoing scans

Development

Testing

Run the test suite to verify functionality:

# Run all tests pytest # Run specific test categories python tests/test_server.py python tests/simple_test.py python tests/test_imports.py # Test the binary command bbot-mcp --help

Project Structure

bbot-mcp/ ├── bbot_mcp/ # Main package │ ├── __init__.py # Package initialization │ └── server.py # MCP server implementation ├── tests/ # Test suite ├── pyproject.toml # Package configuration ├── README.md # This file └── requirements.txt # Development dependencies

Example MCP Client Usage

# Connect to the MCP server and use the tools client = MCPClient("bbot-scanner") # List available modules modules = client.call_tool("list_bbot_modules") # Start a scan scan_result = client.call_tool("start_bbot_scan", { "targets": "example.com", "presets": "web-basic" }) # Check scan status status = client.call_tool("get_scan_status", { "scan_id": scan_result["scan_id"] }) # Wait for scan to complete completion = client.call_tool("wait_for_scan_completion", { "scan_id": scan_result["scan_id"], "timeout": 300 }) # Get results when complete results = client.call_tool("get_scan_results", { "scan_id": scan_result["scan_id"], "limit": 50 })

Security Considerations

  • This tool is designed for authorized security testing only
  • Always ensure you have permission to scan target systems
  • Be aware that bbot scans can be resource-intensive and may take significant time
  • Some modules may be considered intrusive - use the --allow-deadly equivalent flags carefully

Dependency Management

The MCP server includes comprehensive dependency management to prevent sudo password prompts:

Automatic Protection Measures

  • Default Behavior: no_deps=True - Dependencies are disabled by default
  • Environment Variables: Multiple layers of sudo prevention (SUDO_ASKPASS, DEBIAN_FRONTEND, etc.)
  • Stdin Redirection: Blocks all interactive input to prevent hanging
  • Module Exclusions: Problematic modules (sslcert, trufflehog) are automatically excluded
  • Force Configuration: Modules run even if dependencies fail

Key Features

  • Comprehensive Sudo Prevention: Multiple environment variables and configurations prevent any sudo prompts
  • Graceful Degradation: Scans continue even when some modules can't load dependencies
  • Pre-installation Support: Install dependencies manually if needed: pip install <module-deps>
  • macOS Compatibility: Special handling for Homebrew vs APT package manager conflicts

Excluded Modules

You can exclude problematic modules by setting following environment variable:

export BBOT_EXCLUDE_MODULES="trufflehog,sslcert"

Example exclude mentioned modules if you have any dependency issues (i.e. on Mac OS X):

  • sslcert: APT dependency incompatible with macOS Homebrew
  • trufflehog: Dependency installation conflicts

Override Option: Set no_deps=False only if you're certain no sudo prompts will occur

For more information about bbot itself, visit: https://github.com/blacklanternsecurity/bbot

-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables users to run and manage BBOT security scans through the MCP interface. Provides comprehensive tools for executing reconnaissance scans, monitoring progress, and retrieving results with support for concurrent scanning operations.

  1. Features
    1. Installation
      1. From PyPI (Recommended)
      2. From Source
      3. Using uvx (Run without installing)
    2. Install dependencies
      1. Usage
        1. Running the MCP Server
        2. Available Tools
      2. MCP config example:
        1. Scan Management
          1. Scan Lifecycle
          2. Long-running Scans
        2. Development
          1. Testing
          2. Project Structure
        3. Example MCP Client Usage
          1. Security Considerations
            1. Dependency Management
              1. Automatic Protection Measures
              2. Key Features
              3. Excluded Modules

            Related MCP Servers

            • A
              security
              A
              license
              A
              quality
              A Model Control Protocol server that provides access to nmap network scanning functionality, allowing users to run customizable scans, store results, and analyze network security using AI prompts.
              Last updated -
              3
              9
              MIT License
              • Linux
            • -
              security
              F
              license
              -
              quality
              MCP server to perform various OSINT tasks by leveraging common network reconnaissance tools.
              Last updated -
              31
            • -
              security
              A
              license
              -
              quality
              An intelligent layered port scanning service based on MCP protocol, designed for AI assistants and development tools to perform network security analysis with real-time feedback.
              Last updated -
              2
              MIT License

            View all related MCP servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/marlinkcyber/bbot-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server