bloodhound_mcp

BloodHound Model Context Protocol Server

A Model Context Protocol (MCP) server that enables Large Language Models to interact with BloodHound Community Edition data through Claude Desktop. This tool allows security professionals to query and analyze Active Directory attack paths using natural language.

Architecture

This MCP server provides a comprehensive interface to BloodHound Community Edition's REST API, not just a wrapper around Cypher queries. The implementation includes:

API Coverage

• Complete REST API Integration: Utilizes BloodHound CE's full REST API endpoints (/api/v2/domains, /api/v2/users, /api/v2/groups, etc.)
• Structured Data Access: Leverages purpose-built API endpoints for users, computers, groups, OUs, and GPOs
• Advanced Functionality: Includes ADCS analysis, graph search, shortest path algorithms, and edge composition analysis
• Authentication: Implements BloodHound's signature-based authentication system

Why Not Just Cypher Queries?

While Cypher queries are powerful, this MCP goes beyond simple query execution:

• Structured API Responses: Returns properly formatted, paginated data with counts and metadata
• Built-in Relationships: Utilizes BloodHound's pre-computed relationship mappings
• Error Handling: Proper HTTP status code handling and meaningful error messages
• Performance: Leverages BloodHound's optimized endpoints rather than raw graph traversal
• Completeness: Access to administrative rights, sessions, group memberships, and other complex relationships through dedicated endpoints

MCP Benefits

As a proper Model Context Protocol implementation:

• Tool Discoverability: LLM automatically discovers available analysis capabilities
• Type Safety: Strongly typed parameters and responses
• Contextual Help: Built-in documentation and examples for the LLM
• Resource Access: Provides Cypher query examples and patterns as MCP resources

Demo

Watch the demonstration video

Features

Core Capabilities

• Domain Analysis: Query domain information, users, groups, computers, and organizational structure
• User Intelligence: Analyze user privileges, group memberships, sessions, and administrative rights
• Group Analysis: Examine group memberships, controllers, and privilege relationships
• Computer Assessment: Investigate computer privileges, sessions, and administrative access
• Organizational Units: Explore OU structure and contained objects
• Group Policy Objects: Analyze GPO assignments and controllers
• Certificate Services: Investigate ADCS infrastructure and certificate templates
• Custom Cypher Queries: Execute advanced Neo4j queries for complex analysis
• Graph Search: Find shortest paths between security principals

Advanced Features

• Natural language querying of BloodHound data
• Attack path visualization and analysis
• Privilege escalation identification
• Cross-domain relationship analysis
• Kerberoasting target identification
• Administrative relationship mapping

Prerequisites

• Python 3.11+
• uv (Python package manager)
• Claude Desktop
• BloodHound Community Edition instance (accessible via network)
• BloodHound data loaded (from SharpHound, BloodHound.py, etc.)
• BloodHound API credentials (Token ID and Token Key)

Installation

1. Clone the repository

   git clone <repository-url>
   cd bloodhound-mcp
   

2. Install dependencies

   uv sync
   

3. Configure environment variables

   Create a .env file in the project root:

   BLOODHOUND_DOMAIN=your-bloodhound-instance.domain.com
   BLOODHOUND_TOKEN_ID=your-token-id
   BLOODHOUND_TOKEN_KEY=your-token-key
   

Configuration

Claude Desktop Setup

1. Open Claude Desktop and navigate to Settings → Developer Tools
2. Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "bloodhound_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/bloodhound-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

3. Replace /path/to/your/bloodhound-mcp with the actual path to your installation
4. Restart Claude Desktop

BloodHound API Token Setup

1. Log into your BloodHound CE instance
2. Navigate to Administration → API Tokens
3. Create a new token with appropriate permissions
4. Note the Token ID and Token Key for your .env file

Usage

Getting Started

1. Start a new conversation in Claude Desktop
2. Look for the hammer icon (🔨) indicating MCP tools are available
3. Begin by asking about your domains:

What domains are available in BloodHound?

Example Queries

Domain Reconnaissance:

Show me all users in the DOMAIN.LOCAL domain
What computers are in the domain?
Find all Domain Admins

User Analysis:

What administrative rights does john.doe@domain.local have?
Show me all sessions for the user administrator
What groups is this user a member of?

Privilege Escalation:

Find all kerberoastable users
Show me users with DCSync privileges
What computers can I RDP to from this user?

Advanced Analysis:

Run a cypher query to find all paths to Domain Admin
Show me the shortest path from user A to user B
Find all users with SPN set

Security Considerations

Data Sensitivity Warning

This tool processes BloodHound data through Claude Desktop, which means Active Directory information is transmitted to Anthropic's servers. Do not use this tool with production or sensitive BloodHound data.

Recommended Use Cases

• Training environments (GOAD, DetectionLab, etc.)
• Demonstration purposes
• Learning and research
• Non-production domain analysis

Best Practices

• Use isolated lab environments
• Sanitize data before analysis
• Consider local LLM alternatives for sensitive environments
• Regular token rotation for BloodHound API access

Testing

Run the test suite to verify functionality:

# Basic functionality tests
uv run pytest tests/test_basics.py -v

# HTTP request testing
uv run pytest tests/test_bloodhound_http.py -v

# MCP tools testing
uv run pytest tests/test_mcp_tools.py -v

# Integration tests (requires running BloodHound instance)
BLOODHOUND_INTEGRATION_TESTS=1 uv run pytest tests/test_integration.py -v

Contributing

Contributions are welcome! This project is designed for learning and experimentation with MCPs and BloodHound APIs.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

Roadmap

• Enhanced attack path analysis
• Azure Active Directory support
• Advanced graph visualizations
• Asset management integration
• Local LLM compatibility
• Additional ADCS attack scenarios

License

This project is licensed under the GNU General Public License v3.0 - see the file for details.

Acknowledgments

• Orange Cyberdefense for GOAD (used for testing)
• SpecterOps for BloodHound Community Edition
• @jlowin for FastMCP
• @xpn for MCP inspiration through the Mythic MCP project