Skip to content
Back to search

bloodhound_mcp

A Model Context Protocol (MCP) server to converse with data in Bloodhound

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mwnickerson--bloodhound-mcp/badge.svg)](/listings/mwnickerson--bloodhound-mcp)

HTML

<a href="/listings/mwnickerson--bloodhound-mcp"><img src="/api/listings/mwnickerson--bloodhound-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Run the MCP server directly from Git without cloning it first:

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

For a reproducible integration, append a commit after the repository URL, for example `git+https://github.com/mwnickerson/bloodhound_mcp@<commit>`. An `uvx` installation does not read the `.env` from a separate checkout, so the process that launches the MCP client must provide the credential variables.

For development, clone the repository and install its environment:

git clone https://github.com/mwnickerson/bloodhound_mcp.git
cd bloodhound-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

At startup, the MCP server makes a signed, read-only request to `/api/v2/self`. Invalid credentials, connectivity failures, and TLS failures stop the server before it accepts MCP tool calls. The startup request times out after 10 seconds.

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

BLOODHOUND_PORT=8080
BLOODHOUND_SCHEME=http

TLS certificate verification remains enabled when no additional setting is provided. For a trusted lab deployment that uses a self-signed certificate, verification can be explicitly disabled:

BLOODHOUND_VERIFY_TLS=false

Disabling verification weakens transport security and logs a warning. Do not use this option on untrusted networks.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 343 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # BloodHound MCP
  2. [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
  3. A Model Context Protocol (MCP) server that connects LLMs to BloodHound Community Edition and 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.
  4. ## Demo
  5. [Watch the demonstration video](https://youtu.be/eZBT0Iw9CMA)
  6. ---
  7. ## How It Works
  8. The server exposes BloodHound CE's REST API and Neo4j graph through a set of **13 composite MCP tools**, **10 reference resources**, and a **system prompt** tuned for offensive security analysis.
  9. ### Composite Tools
  10. Each tool uses an `info_type` parameter to select what data is returned, keeping the tool surface small and token-efficient:
  11. | Tool | `info_type` Options |
  12. |------|---------------------|
  13. | `domain_info` | `list`, `info`, `users`, `groups`, `computers`, `ous`, `gpos`, `dc_syncers`, `foreign_admins`, `foreign_group_members`, `linked_gpos`, `search` |
  14. | `user_info` | `info`, `sessions`, `memberships`, `admin_rights`, `rdp_rights`, `dcom_rights`, `ps_remote_rights`, `sql_admin_rights`, `constrained_delegation`, `controllables`, `controllers` |
  15. | `group_info` | `info`, `members`, `memberships`, `admin_rights`, `rdp_rights`, `dcom_rights`, `ps_remote_rights`, `controllers`, `controllables` |
  16. | `computer_info` | `info`, `sessions`, `local_admins`, `rdp_rights`, `dcom_rights`, `ps_remote_rights`, `sql_admins`, `constrained_delegation`, `controllables`, `controllers` |
  17. | `ou_info` | `info`, `users`, `groups`, `computers`, `gpos` |
  18. | `gpo_info` | `info`, `controllers` |
  19. | `graph_analysis` | `shortest_path`, `edge_composition`, `search` |
  20. | `adcs_info` | `templates`, `esc_paths` |
  21. | `cypher_query` | `run`, `saved_list`, `saved_get` |
  22. | `data_quality` | `stats`, `platform_list`, `platform_info` |
  23. | `asset_groups` | `list`, `members`, `custom_selectors` |
  24. | `custom_nodes` | `list`, `get`, `create`, `update`, `delete`, `validate_icon`, `extension_list`, `extension_upsert`, `extension_delete`, `extension_edges` |
  25. | `file_upload` | `upload`, `start_job`, `upload_to_job`, `upload_bytes`, `upload_bytes_to_job`, `end_job` |
  26. ### Resources
  27. Reference material the LLM loads on demand — no extra API calls:
  28. | Resource URI | Contents |
  29. |---|---|
  30. | `bloodhound://cypher/reference` | Cypher syntax, schema, property names, patterns |
  31. | `bloodhound://cypher/offensive-queries` | Battle-tested templates: DCSync, Kerberoasting, GPO abuse, delegation, ADCS, shadow credentials, NTLM relay, and more |
  32. | `bloodhound://guides/ad` | AD node types and relationships quick reference |
  33. | `bloodhound://guides/ad-methodology` | Full AD attack methodology and workflow |
  34. | `bloodhound://guides/azure` | Azure/Entra ID analysis quick reference |
  35. | `bloodhound://guides/azure-methodology` | Full Azure attack chains |
  36. | `bloodhound://guides/adcs` | ADCS ESC1–ESC13 quick reference |
  37. | `bloodhound://guides/adcs-methodology` | Detailed ESC analysis and exploitation |
  38. | `bloodhound://opengraph/guide` | Custom node schema design and best practices |
  39. | `bloodhound://opengraph/examples` | SQL Server and Web App OpenGraph examples |
  40. ### System Prompt
  41. The `bloodhound_assistant` prompt includes behavioral rules that guide the LLM:
  42. - Load the offensive query library before writing Cypher for any attack scenario
  43. - Never draw privilege conclusions without checking group memberships and `admincount`
  44. - Respect BloodHound's property naming conventions (`hasspn`, `enabled`, `admincount` — all lowercase)
  45. - Handle uppercase name storage (`DOMAIN ADMINS@CORP.LOCAL`) correctly in filters
  46. - Follow proper DCSync and GPO edge traversal patterns
  47. ---
  48. ## Prerequisites
  49. - Python 3.11+
  50. - [uv](https://docs.astral.sh/uv/)
  51. - BloodHound Community Edition instance with data loaded
  52. - BloodHound API credentials (Token ID + Token Key)
  53. ---
  54. ## Installation
  55. Run the MCP server directly from Git without cloning it first:
  56. ```bash
  57. export BLOODHOUND_DOMAIN=your-bloodhound-instance.domain.com
  58. export BLOODHOUND_TOKEN_ID=your-token-id
  59. export BLOODHOUND_TOKEN_KEY=your-token-key
  60. uvx --from git+https://github.com/mwnickerson/bloodhound_mcp bloodhound-mcp
  61. ```
  62. For a reproducible integration, append a commit after the repository URL, for
  63. example `git+https://github.com/mwnickerson/bloodhound_mcp@<commit>`.
  64. An `uvx` installation does not read the `.env` from a separate checkout, so
  65. the process that launches the MCP client must provide the credential variables.
  66. For development, clone the repository and install its environment:
  67. ```bash
  68. git clone https://github.com/mwnickerson/bloodhound_mcp.git
  69. cd bloodhound-mcp
  70. uv sync
  71. ```
  72. Create a `.env` file in the project root:
  73. ```env
  74. BLOODHOUND_DOMAIN=your-bloodhound-instance.domain.com
  75. BLOODHOUND_TOKEN_ID=your-token-id
  76. BLOODHOUND_TOKEN_KEY=your-token-key
  77. ```
  78. At startup, the MCP server makes a signed, read-only request to
  79. `/api/v2/self`. Invalid credentials, connectivity failures, and TLS failures
  80. stop the server before it accepts MCP tool calls. The startup request times out
  81. after 10 seconds.
  82. The server defaults to `https` on port `443`. Override if needed:
  83. ```env
  84. BLOODHOUND_PORT=8080
  85. BLOODHOUND_SCHEME=http
  86. ```
  87. TLS certificate verification remains enabled when no additional setting is
  88. provided. For a trusted lab deployment that uses a self-signed certificate,
  89. verification can be explicitly disabled:
  90. ```env
  91. BLOODHOUND_VERIFY_TLS=false
  92. ```
  93. Disabling verification weakens transport security and logs a warning. Do not
  94. use this option on untrusted networks.
  95. ---
  96. ## Configuration
  97. ### Claude Desktop
  98. Add to `claude_desktop_config.json`:
  99. ```json
  100. {
  101. "mcpServers": {
  102. "bloodhound_mcp": {
  103. "command": "uvx",
  104. "args": [
  105. "--from",
  106. "git+https://github.com/mwnickerson/bloodhound_mcp",
  107. "bloodhound-mcp"
  108. ]
  109. }
  110. }
  111. }
  112. ```
  113. ### Claude Code
  114. Add to `~/.claude/mcp.json`:
  115. ```json
  116. {
  117. "mcpServers": {
  118. "bloodhound_mcp": {
  119. "type": "stdio",
  120. "command": "uvx",
  121. "args": [
  122. "--from",
  123. "git+https://github.com/mwnickerson/bloodhound_mcp",
  124. "bloodhound-mcp"
  125. ]
  126. }
  127. }
  128. }
  129. ```
  130. ### OpenAI Codex CLI
  131. Add to `~/.codex/config.toml` (or `.codex/config.toml` for project-scoped config):
  132. ```toml
  133. [mcp_servers.bloodhound_mcp]
  134. command = "uvx"
  135. args = ["--from", "git+https://github.com/mwnickerson/bloodhound_mcp", "bloodhound-mcp"]
  136. ```
  137. The server inherits credentials from the process that launches Codex. To keep
  138. them in the MCP configuration instead, pass them explicitly:
  139. ```toml
  140. [mcp_servers.bloodhound_mcp]
  141. command = "uvx"
  142. args = ["--from", "git+https://github.com/mwnickerson/bloodhound_mcp", "bloodhound-mcp"]
  143. [mcp_servers.bloodhound_mcp.env]
  144. BLOODHOUND_DOMAIN = "your-bloodhound-instance.domain.com"
  145. BLOODHOUND_TOKEN_ID = "your-token-id"
  146. BLOODHOUND_TOKEN_KEY = "your-token-key"
  147. ```
  148. ### MCP Inspector
  149. - **Command:** `uvx`
  150. - **Args:** `--from git+https://github.com/mwnickerson/bloodhound_mcp bloodhound-mcp`
  151. ### BloodHound API Token
  152. 1. Log into BloodHound CE or BloodHound Enterprise
  153. 2. Navigate to **Administration** → **API Tokens**
  154. 3. Create a new token and copy the Token ID and Token Key into your `.env`
  155. ---
  156. ## Usage
  157. ### Example Queries
  158. **Reconnaissance:**
  159. ```
  160. What domains are in BloodHound?
  161. Show me all Domain Admins in CORP.LOCAL
  162. Find all kerberoastable users
  163. Which computers have unconstrained delegation?
  164. ```
  165. **User and Group Analysis:**
  166. ```
  167. What admin rights does jsmith@corp.local have?
  168. Show me all sessions for the administrator account
  169. What groups is this user a member of?
  170. Who controls the IT ADMINS group?
  171. ```
  172. **Attack Path Analysis:**
  173. ```
  174. Find the shortest path from jsmith@corp.local to Domain Admins
  175. Who has DCSync rights in the domain?
  176. Show me all GPO abuse paths
  177. Find ADCS ESC1 paths in the domain
  178. ```
  179. **Custom Cypher:**
  180. ```
  181. Run a Cypher query to find all users with SPN set and admincount=1
  182. Find all computers where DOMAIN USERS can RDP
  183. ```
  184. **Collection Uploads:**
  185. ```
  186. Upload this SharpHound ZIP from /tmp/sharphound.zip into BloodHound
  187. Upload these base64-encoded SharpHound ZIP bytes as sharphound.zip
  188. Start an upload job, upload these base64 JSON bytes as users.json, then end the job
  189. ```
  190. Agents that already hold a SharpHound or AzureHound collection in memory should
  191. base64-encode the collection bytes and call:
  192. ```python
  193. file_upload(
  194. info_type="upload_bytes",
  195. file_name="sharphound.zip",
  196. file_bytes_base64="<base64-encoded zip bytes>"
  197. )
  198. ```
  199. For multi-file jobs, call `start_job`, then `upload_bytes_to_job` for each
  200. base64 payload, then `end_job`.
  201. ---
  202. ## OpenGraph Support
  203. 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.
  204. 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`.
  205. 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`.
  206. > Requires BloodHound Enterprise or BloodHound CE 8.0 or later.
  207. > OpenGraph extension management requires BloodHound 9.0.0+ and the corresponding feature flag to be enabled.
  208. ---
  209. ## Security Considerations
  210. 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.**
  211. Recommended use cases:
  212. - Lab environments (GOAD, DetectionLab, custom ranges)
  213. - Training and certification prep
  214. - Research and tool development
  215. - Non-production domain analysis
  216. Best practices:
  217. - Rotate BloodHound API tokens regularly
  218. - Use a read-only API token where possible
  219. - Consider a local LLM bridge for sensitive environments
  220. ---
  221. ## Testing
  222. ```bash
  223. # Full test suite
  224. uv run pytest
  225. # Specific modules
  226. uv run pytest tests/test_main_mcp_tools.py -v
  227. uv run pytest tests/test_bloodhound_api.py -v
  228. # Integration tests (requires a live BloodHound instance)
  229. BLOODHOUND_INTEGRATION_TESTS=1 uv run pytest tests/test_integration.py -v
  230. ```
  231. ---
  232. ## Roadmap
  233. - [ ] Direct Neo4j access mode (bypass REST API for complex graph traversal)
  234. - [ ] Enhanced Azure/Entra ID tooling
  235. - [ ] Improved ADCS attack path coverage
  236. - [ ] Additional OpenGraph examples and templates
  237. ---
  238. ## Contributing
  239. Contributions are welcome. Open an issue to discuss significant changes before submitting a PR.
  240. 1. Fork the repo
  241. 2. Create a feature branch
  242. 3. Add tests for new functionality
  243. 4. Run `uv run pytest` and confirm everything passes
  244. 5. Submit a pull request
  245. ---
  246. ## Acknowledgments
  247. - **SpecterOps** for [BloodHound Community Edition](https://github.com/SpecterOps/BloodHound)
  248. - **Orange Cyberdefense** for [GOAD](https://github.com/Orange-Cyberdefense/GOAD) (used for testing)
  249. - **@jlowin** for [FastMCP](https://github.com/jlowin/fastmcp)
  250. - **@xpn** for MCP inspiration via the Mythic MCP project
  251. ## License
  252. GNU General Public License v3.0 — see [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.