BloodHound MCP Server

MCP server for BloodHound CE (Community Edition) API integration — Active Directory attack path analysis and security assessment.

Overview

This server provides read-only access to BloodHound CE's graph database for Active Directory security analysis. It enables automated queries for attack paths, privilege escalation routes, and vulnerable configurations without requiring direct BloodHound UI interaction.

IMPORTANT: This is an API integration tool, not a CLI wrapper. It communicates directly with the BloodHound CE REST API.

Features

• Attack Path Analysis: Find shortest paths between AD principals
• Privilege Escalation: Identify paths from compromised accounts to high-value targets
• Vulnerability Detection: Discover Kerberoastable and ASREPRoastable users
• Domain Enumeration: List Domain Admins and high-value targets
• Search: Query AD principals by name and type
• Read-Only: No data modification or upload capabilities
• Security: HTTPS enforcement, input validation, rate limiting awareness

Prerequisites

1. BloodHound CE Instance

You need a running BloodHound Community Edition instance with:

• REST API enabled and accessible
• API authentication configured
• Active Directory data already ingested

2. API Credentials

Obtain an API key from your BloodHound CE instance:

# Navigate to BloodHound CE web interface
# Go to: Administration → API Keys → Generate New Key
# Save the generated key securely

3. Environment Variables

Set the following environment variables:

export BLOODHOUND_API_URL="https://bloodhound.corp.example.com"
export BLOODHOUND_API_KEY="your-api-key-here"

Security Notes:

• API URL MUST use HTTPS (except for localhost/127.0.0.1)
• API keys should be stored securely (e.g., in .env files, secrets manager)
• Never commit API keys to version control

Installation

cd bloodhound
bun install
bun run build

Usage

Running the Server

bun run start

Or use with MCP clients that support stdio transport.

Available Tools

1. bloodhound_shortest_path

Find the shortest attack path between two AD principals.

Parameters:

• source (string, required): Source principal name (e.g., "[email protected]")
• target (string, required): Target principal name (e.g., "[email protected]")
• edge_types (array, optional): Edge types to include (e.g., ["MemberOf", "AdminTo", "HasSession"])
• depth (number, optional): Maximum path depth (default: 10, max: 20)

Example:

{
  "source": "[email protected]",
  "target": "DOMAIN [email protected]",
  "depth": 10
}

Response:

{
  "source": "[email protected]",
  "target": "DOMAIN [email protected]",
  "path": [
    {
      "node_name": "[email protected]",
      "node_type": "User",
      "edge_to_next": "MemberOf"
    },
    {
      "node_name": "[email protected]",
      "node_type": "Group",
      "edge_to_next": "AdminTo"
    },
    {
      "node_name": "DC01.CORP.LOCAL",
      "node_type": "Computer",
      "edge_to_next": "HasSession"
    },
    {
      "node_name": "DOMAIN [email protected]",
      "node_type": "Group"
    }
  ],
  "path_length": 4,
  "risk_score": 0.85
}

2. bloodhound_domain_admins

Enumerate Domain Admin users in the environment.

Parameters:

• domain (string, optional): Domain SID or name to filter by
• limit (number, optional): Maximum results (default: 50, max: 500)

Example:

{
  "domain": "CORP.LOCAL",
  "limit": 50
}

Response:

{
  "domain": "CORP.LOCAL",
  "admins": [
    {
      "name": "[email protected]",
      "type": "User",
      "enabled": true,
      "last_logon": "2026-02-09T10:30:00Z",
      "paths_to_da": 0
    },
    {
      "name": "[email protected]",
      "type": "User",
      "enabled": true,
      "last_logon": "2026-01-15T08:00:00Z",
      "paths_to_da": 0
    }
  ],
  "total": 2
}

3. bloodhound_kerberoastable

Find Kerberoastable users (vulnerable to offline password cracking).

Parameters:

• domain (string, optional): Domain SID or name to filter by
• limit (number, optional): Maximum results (default: 50, max: 500)

Example:

{
  "domain": "CORP.LOCAL",
  "limit": 50
}

Response:

{
  "domain": "CORP.LOCAL",
  "users": [
    {
      "name": "[email protected]",
      "spn": "MSSQLSvc/sql01.corp.local:1433",
      "enabled": true,
      "admin_count": 1,
      "last_logon": "2026-02-08T12:00:00Z",
      "password_last_set": "2024-06-01T10:00:00Z"
    }
  ],
  "total": 1
}

Security Context: Kerberoastable users with old passwords are high-priority targets.

4. bloodhound_asreproastable

Find ASREPRoastable users (no Kerberos preauthentication required).

Parameters:

• domain (string, optional): Domain SID or name to filter by
• limit (number, optional): Maximum results (default: 50, max: 500)

Example:

{
  "domain": "CORP.LOCAL",
  "limit": 50
}

Response:

{
  "domain": "CORP.LOCAL",
  "users": [
    {
      "name": "[email protected]",
      "enabled": true,
      "admin_count": 0,
      "last_logon": "2025-12-01T09:00:00Z"
    }
  ],
  "total": 1
}

Security Context: ASREPRoastable users are vulnerable to offline password attacks without authentication.

5. bloodhound_owned_paths

Find attack paths from compromised principals to targets.

Parameters:

• owned_principal (string, required): Already-compromised principal
• target_type (enum, optional): "domain_admin" | "high_value" | "specific" (default: "domain_admin")
• specific_target (string, optional): Specific target principal (required if target_type is "specific")
• depth (number, optional): Maximum path depth (default: 10, max: 20)

Example:

{
  "owned_principal": "[email protected]",
  "target_type": "domain_admin",
  "depth": 10
}

Response:

{
  "source": "[email protected]",
  "paths": [
    {
      "nodes": ["[email protected]", "[email protected]", "DC01.CORP.LOCAL", "DOMAIN [email protected]"],
      "edges": ["MemberOf", "AdminTo", "HasSession"],
      "length": 4
    }
  ],
  "total_paths": 1
}

Use Case: Post-exploitation privilege escalation planning.

6. bloodhound_high_value_targets

List principals marked as high-value targets.

Parameters:

• domain (string, optional): Domain SID or name to filter by
• limit (number, optional): Maximum results (default: 50, max: 500)

Example:

{
  "domain": "CORP.LOCAL",
  "limit": 50
}

Response:

{
  "domain": "CORP.LOCAL",
  "targets": [
    {
      "name": "DOMAIN [email protected]",
      "type": "Group",
      "description": "Domain Admins",
      "incoming_paths_count": 145
    },
    {
      "name": "DC01.CORP.LOCAL",
      "type": "Computer",
      "description": "Primary Domain Controller",
      "incoming_paths_count": 89
    }
  ],
  "total": 2
}

7. bloodhound_search

Search for AD principals by name or properties.

Parameters:

• query (string, required): Search query (1-256 characters)
• type (enum, optional): "user" | "group" | "computer" | "ou" | "gpo" | "domain" | "all" (default: "all")
• limit (number, optional): Maximum results (default: 50, max: 500)

Example:

{
  "query": "admin",
  "type": "user",
  "limit": 50
}

Response:

{
  "results": [
    {
      "name": "[email protected]",
      "type": "User",
      "objectid": "S-1-5-21-...",
      "domain": "CORP.LOCAL",
      "properties": {
        "enabled": true,
        "admincount": 1
      }
    }
  ],
  "total": 1
}

Security Considerations

Input Validation

All inputs are validated:

• Principal names: 1-256 characters, alphanumeric + ._-\@ only
• Path depth: 1-20 hops
• Limits: 1-500 results

Network Security

• HTTPS Required: API URL must use HTTPS (except localhost)
• Authentication: Bearer token authentication with API keys
• No Data Upload: Server is read-only, no data modification

Rate Limiting

BloodHound CE APIs may have rate limits. This server does not implement client-side rate limiting. Monitor your BloodHound instance for 429 Too Many Requests responses.

API Key Management

# Store in .env file (DO NOT commit)
echo "BLOODHOUND_API_URL=https://bloodhound.corp.example.com" >> .env
echo "BLOODHOUND_API_KEY=your-api-key-here" >> .env

# Or use environment variable management tools
export BLOODHOUND_API_URL="https://bloodhound.corp.example.com"
export BLOODHOUND_API_KEY="$(cat /secure/path/to/key.txt)"

Least Privilege

The API key should have:

• Read-only access to graph data
• No administrative privileges
• No data upload/modification permissions

BloodHound CE Setup

Installation

Follow the official BloodHound CE documentation:

• BloodHound CE GitHub
• Installation Guide

Data Collection

Before using this server, you need AD data in BloodHound:

# Using SharpHound (Windows)
SharpHound.exe --CollectionMethods All --Domain corp.local

# Using azurehound (Azure AD)
azurehound -u "[email protected]" -p "password" list --tenant "tenant-id"

# Import into BloodHound CE via UI
# Upload the generated ZIP files

API Configuration

1. Navigate to BloodHound CE web interface
2. Go to Administration → API Keys
3. Click Generate New Key
4. Copy the key immediately (it won't be shown again)
5. Set appropriate permissions (read-only recommended)

Error Handling

The server returns errors in this format:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Principal name contains invalid characters"
    }
  ],
  "isError": true
}

Common errors:

• BLOODHOUND_API_URL environment variable is required: Set the API URL
• BLOODHOUND_API_KEY environment variable is required: Set the API key
• BloodHound API URL must use HTTPS or localhost: Use HTTPS
• BloodHound API error (401): Invalid API key or expired token
• BloodHound API error (404): Principal or resource not found
• BloodHound API error (429): Rate limit exceeded
• Principal name contains invalid characters: Invalid principal format

Development

Building

bun run build

Testing

# Set test environment variables
export BLOODHOUND_API_URL="https://bloodhound-test.corp.local"
export BLOODHOUND_API_KEY="test-api-key"

# Run the server
bun run start

TypeScript Configuration

The project uses:

• Target: ES2022
• Module: ES2022 with bundler resolution
• Strict mode: Enabled
• Runtime: Bun

Architecture

bloodhound/
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── README.md             # This file
└── src/
    ├── index.ts          # Main MCP server
    ├── schemas.ts        # Zod validation schemas
    ├── security.ts       # Security utilities
    └── tools/
        ├── bloodhound-shortest-path.ts
        ├── bloodhound-domain-admins.ts
        ├── bloodhound-kerberoastable.ts
        ├── bloodhound-asreproastable.ts
        ├── bloodhound-owned-paths.ts
        ├── bloodhound-high-value-targets.ts
        └── bloodhound-search.ts

Use Cases

Red Team Operations

• Initial Access: Find ASREPRoastable/Kerberoastable users for credential access
• Privilege Escalation: Map paths from compromised accounts to Domain Admin
• Lateral Movement: Identify intermediate targets in attack paths

Blue Team / Defense

• Attack Surface Analysis: Identify exposures and misconfigurations
• Hardening: Find and fix privilege escalation paths
• Monitoring: Track changes in high-value target exposure

Security Audits

• Compliance: Document AD security posture
• Reporting: Automated extraction of security metrics
• Trend Analysis: Track remediation progress over time

Limitations

• Read-Only: Cannot modify BloodHound data or upload new collections
• API Dependent: Requires BloodHound CE API (not compatible with legacy BloodHound)
• No GraphQL: Uses REST API endpoints, not raw Neo4j queries
• Rate Limits: Subject to BloodHound CE API rate limiting
• Network Required: Requires network access to BloodHound instance

BloodHound CE API Endpoints

This server uses the following API endpoints:

• POST /api/v2/graphs/shortest-path - Shortest path queries
• POST /api/v2/graphs/cypher - Custom Cypher queries
• GET /api/v2/search - Principal search

Refer to the BloodHound CE API documentation for endpoint details.

Troubleshooting

Connection Refused

Error: fetch failed

Solution: Verify BLOODHOUND_API_URL is correct and BloodHound CE is running.

Unauthorized

BloodHound API error (401): Unauthorized

Solution: Check BLOODHOUND_API_KEY is valid and not expired.

No Results

{
  "results": [],
  "total": 0
}

Solution:

• Verify AD data is ingested in BloodHound
• Check query parameters (domain name, principal format)
• Ensure principals exist in the database

HTTPS Error

BloodHound API URL must use HTTPS or localhost

Solution: Use https:// in BLOODHOUND_API_URL or use localhost/127.0.0.1 for testing.

Contributing

This is a security tool. Contributions should:

• Maintain read-only behavior
• Preserve input validation
• Include error handling
• Follow TypeScript strict mode
• Document security implications

License

[Specify license]

Disclaimer

This tool is for authorized security testing and analysis only. Unauthorized access to Active Directory environments is illegal. Users are responsible for:

• Obtaining proper authorization
• Complying with applicable laws and policies
• Securing API credentials
• Monitoring and logging usage

References

• BloodHound CE GitHub
• BloodHound Documentation
• Active Directory Attack Paths
• Kerberoasting
• AS-REP Roasting

Support

For issues related to:

• This MCP Server: Open an issue in this repository
• BloodHound CE: Refer to SpecterOps Support
• Active Directory: Consult Microsoft documentation

Last Updated: 2026-02-09 Version: 1.0.0 Compatibility: BloodHound CE API v2