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. This is currently in the state where it works with Claude Desktop by default.

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

• BloodHound REST API Integration: Utilizes BloodHound CE's REST API endpoints (/api/v2/domains, /api/v2/users, /api/v2/groups, etc.) most relevant to an operators use case. The management apis have been left out as i still dont feel comfortable giving an LLM access to management of BloodHound

• 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 - Outdated will update with a new one at some point

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

• Asset Grouping: Group assets together (Tier Zero, Owned, custom groupings)

• Data Quality: Get more information on the data quality in BloodHound

• OpenGraph Support: CRUD Operations on Custom Nodes to support the newest version of BloodHound!

  • Requires BloodHound 8.0 or greater

  • This is just implemented and has not been througohly tested

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

OpenGraph Usage

OpenGraph is a new feature to BloodHound 8.0. It gives users the power to expand BloodHound beyond standard AD and Azure AD. For more information on OpenGraph please see the below resources

• Awesome Blogpost on the new feature

• Documentation

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

   Note: By default, the server connects using https on port 443. If you're using BloodHound Community Edition with a different configuration, add these optional variables:

   BLOODHOUND_PORT=8080 BLOODHOUND_SCHEME=http

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:

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:

Example Queries

Domain Reconnaissance:

User Analysis:

Privilege Escalation:

Advanced Analysis:

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

  • there are projects coming out that allow for the connecting of MCPs to local llms

• Regular token rotation for BloodHound API access

A note on Local LLM Support

Initially I was planning to allow for this to connect to Local LLMs, however during this process the research and testing has led me in another direction. This direction requires a lot more time and energy that takes away from building a connector for Ollama or other Local LLM support. There are a lot of projects coming out (that I have not tested with this) that can serve as a bridge. Therefore I do not plan on directly making this project work with local LLMs for the time being (this may be something i explore in the future). Hopefully the next evolution of this project will be seen as a worthwhile investment of my time and energy!

Testing

Run the test suite to verify functionality:

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 LICENSE 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