BloodHound Enterprise MCP

A Model Context Protocol (MCP) server that connects LLMs to BloodHound Enterprise. Ask questions in natural language, get attack path analysis, run Cypher queries, and explore Active Directory, Azure/Entra ID, and OpenGraph environments — all from your AI assistant.

Fork Attribution

This project is a fork of mwnickerson/bloodhound_mcp. The original project and its contributors created the BloodHound MCP foundation this fork builds on.

This fork modifies the original BloodHound Community Edition-focused implementation for BloodHound Enterprise API coverage, multi-tenant MCP configuration, expanded endpoint wrappers, Enterprise attack path/risk posture workflows, and BHE-specific documentation. The project remains licensed under GPL-3.0; see LICENSE and NOTICE.

---

How It Works

The server exposes BloodHound Enterprise's REST API and Neo4j graph through a set of composite MCP tools, reference resources, and a system prompt tuned for offensive security analysis.

Composite Tools

Each tool uses an info_type parameter to select what data is returned, keeping the tool surface small and token-efficient:

Tool	info_type Options
domain_info	list, info, search, users, groups, computers, controllers, gpos, ous, dc_syncers, foreign_admins, foreign_gpo_controllers, foreign_groups, foreign_users, inbound_trusts, outbound_trusts, linked_gpos, adcs_escalations
entity_info	base_info, base_controllables, base_controllers, container_info, container_controllers, azure_entity
user_info	info, sessions, memberships, admin_rights, rdp_rights, dcom_rights, ps_remote_rights, sql_admin_rights, constrained_delegation, controllables, controllers
group_info	info, members, memberships, admin_rights, rdp_rights, dcom_rights, ps_remote_rights, controllers, controllables
computer_info	info, sessions, local_admins, rdp_rights, dcom_rights, ps_remote_rights, sql_admins, constrained_delegation, controllables, controllers
ou_info	info, users, groups, computers, gpos
gpo_info	info, computers, controllers, ous, tier_zeros, users
graph_analysis	kinds, search, shortest_path, edge_composition, relay_targets, pathfinding, acl_inheritance
adcs_info	cert_template_info, cert_template_controllers, cert_template_published_to_cas, root_ca_info, root_ca_controllers, root_ca_pki_hierarchy, enterprise_ca_info, enterprise_ca_controllers, enterprise_ca_pki_hierarchy, enterprise_ca_published_templates, aia_ca_info, aia_ca_controllers, aia_ca_pki_hierarchy, nt_auth_store_info, nt_auth_store_controllers, nt_auth_store_trusted_cas
cypher_query	run, interpret, list_saved, create_saved, get_saved, update_saved, delete_saved, share_saved, saved_permissions, export_saved, import_saved, export_saved_many, validate
attack_paths	domain_findings, finding_trends, types, start_analysis, details, domain_available_types, domain_details, domain_sparkline, acceptance
risk_posture	stats, history
enterprise_info	version, spec, audit, config, features
enterprise_admin	self, permissions, permission, roles, role, users, users_minimal, user, saml, saml_sso, saml_provider, sso_providers, sso_signing_certificate
data_quality	completeness, ad_domain, azure_tenant, platform
asset_groups	list, get, create, update, delete, collections, custom_selectors, members, member_counts, combo_node, create_selectors, update_selectors, delete_selector, list_tags, create_tag, tag_members, tag_member_selectors, tag_member_counts, tag_selectors, tag_selector_members, tag_selector_member_counts, preview_tag_selectors, search_tags, tag_history, search_tag_history, certifications, update_certifications
custom_nodes	list, get, create, update, delete, validate_icon, extension_list, extension_upsert, extension_delete, extension_edges
file_upload	upload, start_job, upload_to_job, end_job, list_jobs, completed_tasks, accepted_types
operations_info	datapipe_status, analysis, meta_nodes, meta_tree, meta_entity
collection_info	collector_manifest, collector_checksum, kennel_manifest, kennel_enterprise_manifest, clients, client, client_completed_tasks, client_completed_jobs, jobs_available, jobs_finished, jobs, job_current, job, job_log, tasks_available, tasks_finished, tasks, task_current, task, task_log, events, event

Resources

Reference material the LLM loads on demand — no extra API calls:

Resource URI	Contents
bloodhound://cypher/reference	Cypher syntax, schema, property names, patterns
bloodhound://cypher/query-building-reference	Quick query-building syntax patterns
bloodhound://cypher/supported-syntax	Supported BloodHound Cypher syntax, caveats, and unsupported constructs
bloodhound://cypher/offensive-queries	Battle-tested templates: DCSync, Kerberoasting, GPO abuse, delegation, ADCS, shadow credentials, NTLM relay, and more
bloodhound://guides/ad	AD node types and relationships quick reference
bloodhound://guides/ad-methodology	Full AD attack methodology and workflow
bloodhound://guides/azure	Azure/Entra ID analysis quick reference
bloodhound://guides/azure-methodology	Full Azure attack chains
bloodhound://guides/adcs	ADCS ESC1–ESC13 quick reference
bloodhound://guides/adcs-methodology	Detailed ESC analysis and exploitation
bloodhound://opengraph/guide	Custom node schema design and best practices
bloodhound://opengraph/examples	SQL Server and Web App OpenGraph examples

System Prompt

The bloodhound_assistant prompt includes behavioral rules that guide the LLM:

• Load the offensive query library before writing Cypher for any attack scenario
• Never draw privilege conclusions without checking group memberships and admincount
• Respect BloodHound's property naming conventions (hasspn, enabled, admincount — all lowercase)
• Handle uppercase name storage (DOMAIN ADMINS@CORP.LOCAL) correctly in filters
• Follow proper DCSync and GPO edge traversal patterns

---

Prerequisites

• Python 3.11+
• uv
• BloodHound Enterprise instance with data loaded
• BloodHound API credentials (Token ID + Token Key)

---

Installation

git clone https://github.com/mwnickerson/bloodhound_mcp.git ~/git/bhe_mcp
cd ~/git/bhe_mcp
uv sync

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

The server defaults to https on port 443. Override if needed:

BLOODHOUND_PORT=8080
BLOODHOUND_SCHEME=http

---

Configuration

Claude Desktop

Add to claude_desktop_config.json:

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

Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "bhe_mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/bhe_mcp",
        "run",
        "main.py"
      ]
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml (or .codex/config.toml for project-scoped config):

[mcp_servers.bhe_mcp]
command = "uv"
args = ["--directory", "/path/to/bhe_mcp", "run", "main.py"]

Since the server loads credentials from .env automatically, no env block is needed. If you prefer to pass them explicitly:

[mcp_servers.bhe_mcp]
command = "uv"
args = ["--directory", "/path/to/bhe_mcp", "run", "main.py"]

[mcp_servers.bhe_mcp.env]
BLOODHOUND_DOMAIN = "your-bloodhound-instance.domain.com"
BLOODHOUND_TOKEN_ID = "your-token-id"
BLOODHOUND_TOKEN_KEY = "your-token-key"

For multiple BHE tenants, point each MCP server at the same checkout and give each one its own env file. This keeps demo and maplesyrup distinct by server name and by the codename in the env file path:

[mcp_servers.bloodhound_demo]
command = "uv"
args = ["--directory", "/path/to/bhe_mcp", "run", "main.py"]

[mcp_servers.bloodhound_demo.env]
UV_CACHE_DIR = "/path/to/uv-cache"
BLOODHOUND_ENV_FILE = "/path/to/bloodhound_demo.env"

[mcp_servers.bloodhound_maplesyrup]
command = "uv"
args = ["--directory", "/path/to/bhe_mcp", "run", "main.py"]

[mcp_servers.bloodhound_maplesyrup.env]
UV_CACHE_DIR = "/path/to/uv-cache"
BLOODHOUND_ENV_FILE = "/path/to/bloodhound_maplesyrup.env"

MCP Inspector

• Command: uv
• Args: --directory /path/to/bhe_mcp run main.py

BloodHound API Token

1. Log into BloodHound Enterprise
2. Navigate to Administration → API Tokens
3. Create a new token and copy the Token ID and Token Key into your .env

---

Usage

Example Queries

Reconnaissance:

What domains are in BloodHound?
Show me all Domain Admins in CORP.LOCAL
Find all kerberoastable users
Which computers have unconstrained delegation?

User and Group Analysis:

What admin rights does jsmith@corp.local have?
Show me all sessions for the administrator account
What groups is this user a member of?
Who controls the IT ADMINS group?

Attack Path Analysis:

Find the shortest path from jsmith@corp.local to Domain Admins
Who has DCSync rights in the domain?
Show me all GPO abuse paths
Find ADCS ESC1 paths in the domain

Custom Cypher:

Run a Cypher query to find all users with SPN set and admincount=1
Find all computers where DOMAIN USERS can RDP

---

OpenGraph Support

BloodHound 8.0+ supports custom node types via OpenGraph, letting you model non-AD infrastructure (cloud resources, databases, custom assets) in the same graph as Active Directory.

The custom_nodes tool handles legacy CRUD operations on node type display configurations through /api/v2/custom-nodes. For BloodHound v9.0.0+ instances with OpenGraph extension management enabled, the same composite tool also supports /api/v2/extensions and /api/v2/extensions-edges via extension_list, extension_upsert, extension_delete, and extension_edges.

Use the bloodhound://opengraph/guide and bloodhound://opengraph/examples resources for schema design and Cypher patterns. For structured OpenGraph schemas, upsert the extension schema first, then ingest collection data with file_upload.

Requires BloodHound 8.0 or later. OpenGraph extension management requires BloodHound 9.0.0+ and the corresponding feature flag to be enabled.

---

Security Considerations

BloodHound data processed through this tool is transmitted to your LLM provider's servers. Do not use this with production AD data unless you have assessed that risk.

Recommended use cases:

• Lab environments (GOAD, DetectionLab, custom ranges)
• Training and certification prep
• Research and tool development
• Non-production domain analysis

Best practices:

• Rotate BloodHound API tokens regularly
• Use a read-only API token where possible
• Consider a local LLM bridge for sensitive environments

---

Testing

# Full test suite
uv run pytest

# Specific modules
uv run pytest tests/test_main_mcp_tools.py -v
uv run pytest tests/test_bloodhound_api.py -v

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

---

Contributing

Contributions are welcome. Open an issue to discuss significant changes before submitting a PR.

1. Fork the repo
2. Create a feature branch
3. Add tests for new functionality
4. Run uv run pytest and confirm everything passes
5. Submit a pull request

---

Acknowledgments

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

License

GNU General Public License v3.0 — see LICENSE for details.