BloodHound Model Context Protocol Server

BloodHound MCP

一个 Model Context Protocol（MCP）服务，可将大模型连接到 BloodHound Community Edition 和 BloodHound Enterprise。通过自然语言提问、获取攻击路径分析、运行 Cypher 查询，并探索 Active Directory、Azure/Entra ID 和 OpenGraph 环境——所有操作均可通过你的 AI 助手完成。

演示

观看演示视频

---

工作原理

该服务通过 13 个复合 MCP 工具、10 个参考资源和一个经过调整、用于攻击性安全分析的系统提示词，开放 BloodHound CE 的 REST API 和 Neo4j 图谱。

复合工具

每个工具都使用 info_type 参数选择要返回的数据，从而保持工具数量精简并提高令牌效率：

工具	info_type 选项
domain_info	list、info、users、groups、computers、ous、gpos、dc_syncers、foreign_admins、foreign_group_members、linked_gpos、search
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、controllers
graph_analysis	shortest_path、edge_composition、search
adcs_info	templates、esc_paths
cypher_query	run、saved_list、saved_get
data_quality	stats、platform_list、platform_info
asset_groups	list、members、custom_selectors
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、upload_bytes、upload_bytes_to_job、end_job

资源

大模型按需加载的参考资料——无需额外的 API 调用：

资源 URI	内容
bloodhound://cypher/reference	Cypher 语法、架构、属性名称和模式
bloodhound://cypher/offensive-queries	经实战验证的模板：DCSync、Kerberoasting、GPO 滥用、委派、ADCS、影子凭据、NTLM 中继等
bloodhound://guides/ad	AD 节点类型和关系速查
bloodhound://guides/ad-methodology	完整的 AD 攻击方法和工作流
bloodhound://guides/azure	Azure/Entra ID 分析速查
bloodhound://guides/azure-methodology	完整的 Azure 攻击链
bloodhound://guides/adcs	ADCS ESC1–ESC13 速查
bloodhound://guides/adcs-methodology	详细的 ESC 分析和利用方法
bloodhound://opengraph/guide	自定义节点架构设计和最佳实践
bloodhound://opengraph/examples	SQL Server 和 Web App OpenGraph 示例

系统提示词

bloodhound_assistant 提示词包含用于指导大模型行为的规则：

• 针对任何攻击场景编写 Cypher 前，先加载攻击性查询库
• 未检查组成员关系和 admincount 前，绝不推断权限
• 遵循 BloodHound 的属性命名约定（hasspn、enabled、admincount——全部使用小写）
• 在筛选条件中正确处理大写名称存储（DOMAIN [email protected]）
• 遵循正确的 DCSync 和 GPO 边遍历模式

---

前置条件

• Python 3.11+
• uv
• 已加载数据的 BloodHound Community Edition 实例
• BloodHound API 凭据（Token ID + Token Key）

---

安装

无需先克隆仓库，即可直接从 Git 运行 MCP 服务：

export BLOODHOUND_DOMAIN=your-bloodhound-instance.domain.com
export BLOODHOUND_TOKEN_ID=your-token-id
export BLOODHOUND_TOKEN_KEY=your-token-key
uvx --from git+https://github.com/mwnickerson/bloodhound_mcp bloodhound-mcp

如需可复现的集成，可在仓库 URL 后附加提交，例如 git+https://github.com/mwnickerson/bloodhound_mcp@<commit>。 uvx 安装不会读取单独检出目录中的 .env，因此，启动 MCP 客户端的进程必须提供凭据变量。

如需进行开发，请克隆仓库并安装其环境：

git clone https://github.com/mwnickerson/bloodhound_mcp.git
cd bloodhound-mcp
uv sync

在项目根目录中创建 .env 文件：

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

启动时，MCP 服务会向 /api/v2/self 发出带签名的只读请求。凭据无效、连接失败或 TLS 失败时，服务会在接受 MCP 工具调用前停止。启动请求的超时时间为 10 秒。

服务默认使用端口 443 上的 https。如有需要，可覆盖默认值：

BLOODHOUND_PORT=8080
BLOODHOUND_SCHEME=http

未提供其他设置时，TLS 证书验证仍会启用。对于使用自签名证书的可信实验室部署，可以显式禁用验证：

BLOODHOUND_VERIFY_TLS=false

禁用验证会降低传输安全性，并记录警告。请勿在不可信网络中使用此选项。

---

配置

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "bloodhound_mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mwnickerson/bloodhound_mcp",
        "bloodhound-mcp"
      ]
    }
  }
}

Claude Code

添加到 ~/.claude/mcp.json：

{
  "mcpServers": {
    "bloodhound_mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mwnickerson/bloodhound_mcp",
        "bloodhound-mcp"
      ]
    }
  }
}

OpenAI Codex CLI

添加到 ~/.codex/config.toml（项目范围的配置则添加到 .codex/config.toml）：

[mcp_servers.bloodhound_mcp]
command = "uvx"
args = ["--from", "git+https://github.com/mwnickerson/bloodhound_mcp", "bloodhound-mcp"]

服务会继承启动 Codex 的进程所提供的凭据。如需将凭据保留在 MCP 配置中，请显式传入：

[mcp_servers.bloodhound_mcp]
command = "uvx"
args = ["--from", "git+https://github.com/mwnickerson/bloodhound_mcp", "bloodhound-mcp"]

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

MCP Inspector

• 命令： uvx
• 参数： --from git+https://github.com/mwnickerson/bloodhound_mcp bloodhound-mcp

BloodHound API Token

1. 登录 BloodHound CE 或 BloodHound Enterprise
2. 前往 管理 → API Tokens
3. 创建新令牌，并将 Token ID 和 Token Key 复制到 .env 中

---

用法

查询示例

侦察：

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

用户和组分析：

What admin rights does [email protected] have?
Show me all sessions for the administrator account
What groups is this user a member of?
Who controls the IT ADMINS group?

攻击路径分析：

Find the shortest path from [email protected] to Domain Admins
Who has DCSync rights in the domain?
Show me all GPO abuse paths
Find ADCS ESC1 paths in the domain

自定义 Cypher：

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

收集数据上传：

Upload this SharpHound ZIP from /tmp/sharphound.zip into BloodHound
Upload these base64-encoded SharpHound ZIP bytes as sharphound.zip
Start an upload job, upload these base64 JSON bytes as users.json, then end the job

已在内存中持有 SharpHound 或 AzureHound 收集数据的 Agent，应先对收集数据的字节进行 base64 编码，然后调用：

file_upload(
    info_type="upload_bytes",
    file_name="sharphound.zip",
    file_bytes_base64="<base64-encoded zip bytes>"
)

对于多文件任务，请先调用 start_job，然后对每个 base64 负载调用 upload_bytes_to_job，最后调用 end_job。

---

OpenGraph 支持

BloodHound 8.0+ 支持通过 OpenGraph 添加自定义节点类型，让你能够在与 Active Directory 相同的图中建模非 AD 基础设施（云资源、数据库、自定义资产）。

custom_nodes 工具通过 /api/v2/custom-nodes 处理节点类型显示配置的旧版 CRUD 操作。对于启用了 OpenGraph 扩展管理的 BloodHound v9.0.0+ 实例，同一个组合工具还支持通过 extension_list、extension_upsert、extension_delete 和 extension_edges 操作 /api/v2/extensions 和 /api/v2/extensions-edges。

使用 bloodhound://opengraph/guide 和 bloodhound://opengraph/examples 资源了解架构设计和 Cypher 模式。对于结构化的 OpenGraph 架构，请先执行扩展架构的 upsert，然后通过 file_upload 导入收集数据。

需要 BloodHound Enterprise 或 BloodHound CE 8.0 或更高版本。 OpenGraph 扩展管理需要 BloodHound 9.0.0+，并启用相应的功能标志。

---

安全注意事项

通过此工具处理的 BloodHound 数据会传输到你的大模型提供商的服务器。除非已评估相关风险，否则请勿将此工具用于生产 AD 数据。

推荐用例：

• 实验室环境（GOAD、DetectionLab、自定义靶场）
• 培训和认证备考
• 研究和工具开发
• 非生产域分析

最佳实践：

• 定期轮换 BloodHound API 令牌
• 尽可能使用只读 API 令牌
• 对于敏感环境，可考虑使用本地大模型桥接

---

测试

# 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

---

路线图

• 直接访问 Neo4j 模式（绕过 REST API，进行复杂的图遍历）
• 增强 Azure/Entra ID 工具
• 改进 ADCS 攻击路径覆盖范围
• 添加更多 OpenGraph 示例和模板

---

贡献

欢迎贡献。在提交 PR 之前，请先通过创建议题讨论重大更改。

1. Fork 仓库
2. 创建功能分支
3. 为新功能添加测试
4. 运行 uv run pytest 并确认所有测试均通过
5. 提交拉取请求

---

致谢

• 感谢 SpecterOps 提供 BloodHound Community Edition
• 感谢 Orange Cyberdefense 提供 GOAD（用于测试）
• 感谢 @jlowin 提供 FastMCP
• 感谢 @xpn 通过 Mythic MCP 项目带来的 MCP 灵感

许可证

GNU General Public License v3.0 — 详情请参阅 LICENSE。