Skip to content
Back to search

purple-mcp

Access SentinelOne's Purple AI and security services through the Model Context Protocol (MCP) - query alerts, vulnerabilities, misconfigurations, and inventory

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/sentinel-one--purple-mcp/badge.svg)](/listings/sentinel-one--purple-mcp)

HTML

<a href="/listings/sentinel-one--purple-mcp"><img src="/api/listings/sentinel-one--purple-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.

These steps run a script from the network that findsafeskills does not scan.

Using uv (Recommended for Local Development or Deployment)

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set credentials
export PURPLEMCP_CONSOLE_TOKEN="your_token"
export PURPLEMCP_CONSOLE_BASE_URL="https://your-console.sentinelone.net"

# Run
uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode=stdio

⚠️ Security note ⚠️

For production or security-sensitive environments, pin to a specific commit hash instead of using the default branch to reduce supply chain risk from the our [releases](https://github.com/Sentinel-One/purple-mcp/releases) or our verified commits in [main](https://github.com/Sentinel-One/purple-mcp/commits/main) branch.

# Run with pinned hash
uvx --from git+https://github.com/Sentinel-One/purple-mcp.git@<commit-hash> purple-mcp --mode=stdio

Using Docker

Follow instructions for Docker Deployment [here](deploy/README.md#using-docker)

Using Amazon Bedrock AgentCore

Follow instructions for Amazon Bedrock AgentCore Deployment [here](deploy/README.md#using-amazon-bedrock-agentcore)

Using Amazon Elastic Container Service (ECS)

Follow instructions for Amazon Elastic Container Service Deployment [here](deploy/README.md#using-amazon-elastic-container-service-ecs)

Using a Cloud Provider

For cloud deployments, see [Deployment Guide](deploy/cloud/CLOUD_SETUP.md).

**Note:** Purple AI MCP does not include built-in authentication. For network-exposed deployments, place it behind a reverse proxy or load balancer. See [cloud Setup](deploy/cloud/CLOUD_SETUP.md) for cloud load balancer configurations (AWS ALB, GCP Cloud Load Balancing, Azure Application Gateway) or nginx examples for self-hosted deployments.

---

Your token needs Account or Site level permissions (not Global). Get one from Policy & Settings → User Management → Service Users in your console. Currently, this server only supports tokens that have access to a single Account or Site. If you need to access multiple sites, you will need to run multiple MCP servers with Account-specific or Site-specific tokens.

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 · 386 lines

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

  1. <picture>
  2. <source media="(prefers-color-scheme: dark)" type="image/svg+xml" srcset="https://www.sentinelone.com/wp-content/themes/sentinelone/assets/svg/header-logo-light.svg">
  3. <source media="(prefers-color-scheme: light)" type="image/svg+xml" srcset="https://www.sentinelone.com/wp-content/themes/sentinelone/assets/svg/header-logo-dark.svg">
  4. <img alt="SentinelOne" src="https://www.sentinelone.com/wp-content/themes/sentinelone/assets/svg/header-logo-light.svg">
  5. </picture>
  6. # Purple AI MCP Server
  7. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  8. Purple AI MCP Server allows you to access SentinelOne Services with any MCP client.
  9. ## Features
  10. This server exposes SentinelOne's platform through the Model Context Protocol:
  11. - **Purple AI**: Ask security questions, investigate threats
  12. - **Events**: Run PowerQueries on events in your SentinelOne data lake
  13. - **Alerts**: Query, search, and investigate alerts
  14. - **Vulnerabilities**: Track CVEs and security findings
  15. - **Misconfigurations**: Analyze security posture issues
  16. - **Inventory**: Ask questions about endpoints, cloud resources, identities, and network devices
  17. - **CVE Search**: Query public CVE databases for vulnerability details
  18. - **Threat Intelligence**: Get file, URL, domain, and IP analysis from VirusTotal
  19. Purple AI MCP is a read-only service - you cannot make changes to your account or any objects
  20. within your account from this MCP.
  21. ## Quick Start
  22. ### Using uv (Recommended for Local Development or Deployment)
  23. ```bash
  24. # Install uv if you don't have it
  25. curl -LsSf https://astral.sh/uv/install.sh | sh
  26. # Set credentials
  27. export PURPLEMCP_CONSOLE_TOKEN="your_token"
  28. export PURPLEMCP_CONSOLE_BASE_URL="https://your-console.sentinelone.net"
  29. # Run
  30. uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode=stdio
  31. ```
  32. #### ⚠️ Security note ⚠️
  33. For production or security-sensitive environments, pin to a specific commit hash instead of using
  34. the default branch to reduce supply chain risk from the our
  35. [releases](https://github.com/Sentinel-One/purple-mcp/releases) or our verified commits in
  36. [main](https://github.com/Sentinel-One/purple-mcp/commits/main) branch.
  37. ```bash
  38. # Run with pinned hash
  39. uvx --from git+https://github.com/Sentinel-One/purple-mcp.git@<commit-hash> purple-mcp --mode=stdio
  40. ```
  41. ### Using Docker
  42. Follow instructions for Docker Deployment [here](deploy/README.md#using-docker)
  43. ### Using Amazon Bedrock AgentCore
  44. Follow instructions for Amazon Bedrock AgentCore Deployment
  45. [here](deploy/README.md#using-amazon-bedrock-agentcore)
  46. ### Using Amazon Elastic Container Service (ECS)
  47. Follow instructions for Amazon Elastic Container Service Deployment
  48. [here](deploy/README.md#using-amazon-elastic-container-service-ecs)
  49. ### Using a Cloud Provider
  50. For cloud deployments, see [Deployment Guide](deploy/cloud/CLOUD_SETUP.md).
  51. **Note:** Purple AI MCP does not include built-in authentication. For network-exposed deployments,
  52. place it behind a reverse proxy or load balancer. See [cloud Setup](deploy/cloud/CLOUD_SETUP.md)
  53. for cloud load balancer configurations (AWS ALB, GCP Cloud Load Balancing, Azure Application
  54. Gateway) or nginx examples for self-hosted deployments.
  55. ---
  56. Your token needs Account or Site level permissions (not Global). Get one from Policy & Settings →
  57. User Management → Service Users in your console. Currently, this server only supports tokens that
  58. have access to a single Account or Site. If you need to access multiple sites, you will need to run
  59. multiple MCP servers with Account-specific or Site-specific tokens.
  60. ## Authentication
  61. Purple MCP uses a SentinelOne Console token configured at startup via environment variables. The
  62. server authenticates with your SentinelOne Console using the provided token and base URL.
  63. ```bash
  64. # Configure authentication credentials
  65. PURPLEMCP_CONSOLE_TOKEN=YOUR_CONSOLE_TOKEN
  66. PURPLEMCP_CONSOLE_BASE_URL=https://console.sentinelone.net
  67. ```
  68. In addition you may define a console scope for Purple AI query operations:
  69. ```bash
  70. PURPLEMCP_PURPLE_AI_CONSOLE_ACCOUNT_ID=1234567890123456789
  71. ```
  72. This will scope Purple AI queries to account-scope with id `1234567890123456789`.
  73. **Health Check Endpoints:**
  74. The following endpoints bypass authentication to support container orchestration systems
  75. (Kubernetes, Docker, etc.):
  76. - `/health`, `/ready`, `/ping`
  77. These endpoints return only basic status (`{"status": "ok"}`) and do not expose sensitive
  78. information. See [SECURITY.md](SECURITY.md) for details.
  79. ## Clients
  80. Purple AI MCP supports `stdio`, `sse`, and `streamable-http` protocols and should work in any
  81. client that supports MCP. Some sample configurations are listed below.
  82. ### Claude Desktop
  83. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
  84. `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
  85. ```json
  86. {
  87. "mcpServers": {
  88. "purple-mcp": {
  89. "command": "uvx",
  90. "args": [
  91. "--from",
  92. "git+https://github.com/Sentinel-One/purple-mcp.git",
  93. "purple-mcp",
  94. "--mode",
  95. "stdio"
  96. ],
  97. "env": {
  98. "PURPLEMCP_CONSOLE_TOKEN": "your_token",
  99. "PURPLEMCP_CONSOLE_BASE_URL": "https://your-console.sentinelone.net"
  100. }
  101. }
  102. }
  103. }
  104. ```
  105. ### Claude Code
  106. Run this command in a terminal:
  107. `claude mcp add --transport stdio purple-mcp --env PURPLEMCP_CONSOLE_TOKEN=your_token --env PURPLEMCP_CONSOLE_BASE_URL=https://your-console.sentinelone.net -- uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode stdio`
  108. ### OpenAI Codex
  109. Run this command in a terminal:
  110. `codex mcp add purple-mcp --env PURPLEMCP_CONSOLE_TOKEN=your_token --env PURPLEMCP_CONSOLE_BASE_URL=https://your-console.sentinelone.net -- uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode stdio`
  111. ### Pydantic AI
  112. Here is some example Python code to use Purple MCP with a Pydantic AI Agent.
  113. ```python
  114. from pydantic_ai import Agent
  115. from pydantic_ai.mcp import MCPServerStdio
  116. server = MCPServerStdio(
  117. 'uvx', args=["--from", "git+https://github.com/Sentinel-One/purple-mcp.git", "purple-mcp", "--mode", "stdio"], timeout=10
  118. )
  119. agent = Agent('anthropic:claude-haiku-4-5', toolsets=[server])
  120. ```
  121. ### Zed
  122. Edit `~/.zed/mcp.json`:
  123. ```json
  124. {
  125. "mcpServers": {
  126. "purple-mcp": {
  127. "enabled": true,
  128. "source": "custom",
  129. "command": "uvx",
  130. "args": [
  131. "--from",
  132. "git+https://github.com/Sentinel-One/purple-mcp.git",
  133. "purple-mcp",
  134. "--mode",
  135. "stdio"
  136. ],
  137. "env": {
  138. "PURPLEMCP_CONSOLE_TOKEN": "your_token",
  139. "PURPLEMCP_CONSOLE_BASE_URL": "https://your-console.sentinelone.net"
  140. }
  141. }
  142. }
  143. }
  144. ```
  145. ### Other Clients
  146. For debugging or to host server for multiple clients, run in streamable-http mode and connect via
  147. mcp-remote:
  148. ```bash
  149. # Terminal 1: Start server
  150. export PURPLEMCP_CONSOLE_TOKEN="your_token"
  151. export PURPLEMCP_CONSOLE_BASE_URL="https://your-console.sentinelone.net"
  152. uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode streamable-http --host localhost --port 8000
  153. # Terminal 2: Connect with any client
  154. npx -y mcp-remote http://127.0.0.1:8000/mcp
  155. ```
  156. We suggest you **do not** expose Purple AI MCP on a network at this time, as there is no
  157. authentication enforced and anyone could access a configured SentinelOne account.
  158. ## Available Tools
  159. ### Purple AI
  160. - `purple_ai(query)` - Ask security questions
  161. ### Data Lake
  162. - `powerquery(query, start_time, end_time)` - Run PowerQuery analytics
  163. ### Alerts
  164. - `get_alert(alert_id)` - Get alert details
  165. - `list_alerts(first, after, view_type)` - List recent alerts
  166. - `search_alerts(filters, first)` - Search with filters
  167. - `get_alert_notes(alert_id)` - Get alert comments
  168. - `get_alert_history(alert_id)` - View alert timeline
  169. ### Vulnerabilities
  170. - `get_vulnerability(id)` - Get vulnerability details
  171. - `list_vulnerabilities(first, after)` - List recent vulnerabilities
  172. - `search_vulnerabilities(filters, first)` - Search CVEs and findings
  173. - `get_vulnerability_notes(id)` - Get comments
  174. - `get_vulnerability_history(id)` - View timeline
  175. ### Misconfigurations
  176. - `get_misconfiguration(id)` - Get misconfiguration details
  177. - `list_misconfigurations(first, after)` - List recent issues
  178. - `search_misconfigurations(filters, first)` - Search by criteria
  179. - `get_misconfiguration_notes(id)` - Get comments
  180. - `get_misconfiguration_history(id)` - View timeline
  181. ### Asset Inventory
  182. - `get_inventory_item(item_id, fetch_fields)` - Get asset details with field filtering
  183. - `list_inventory_items(limit, skip, surface, fetch_fields)` - List assets by surface type
  184. - `search_inventory_items(filters, limit, skip, fetch_fields)` - Search with advanced filters
  185. **Field Filtering:** All inventory tools support `fetch_fields` parameter to control returned data:
  186. - Presets: `MINIMAL` (7 fields), `STANDARD` (13 fields), `ALL` (~200+ fields)
  187. - Custom lists: Specify exact fields in camelCase, e.g., `["id", "name", "resourceType"]`
  188. - Use `get_inventory_item(item_id, fetch_fields="ALL")` on a single item to discover available
  189. field names
  190. ### CVE Search (External)
  191. Query public CVE databases (cve-search.org) for vulnerability information:
  192. - `cve_search_by_id(cve_id)` - Get detailed CVE information by ID
  193. - `cve_search_by_vendor(vendor, product)` - Search CVEs by vendor/product
  194. - `cve_database_status()` - Get database update information
  195. **Note:** No API key required. Data sourced from CIRCL.LU's cve-search.org.
  196. ### Threat Intelligence (External)
  197. Query VirusTotal/Google Threat Intelligence for file, URL, domain, and IP analysis:
  198. - `threat_intel_by_hash(hash_value)` - Get threat intel for file hash (MD5/SHA1/SHA256)
  199. - `threat_intel_by_url(url)` - Get URL reputation and analysis
  200. - `threat_intel_by_domain(domain)` - Get domain threat intelligence
  201. - `threat_intel_by_ip(ip_address)` - Get IP address threat intelligence
  202. - `threat_intel_get_file_relationships(hash_value, relationship_type)` - Get file relationships
  203. (contacted domains/IPs, similar files)
  204. - `threat_intel_search(query)` - Search VirusTotal Intelligence (Premium API required)
  205. - `threat_intel_get_file_behavior(hash_value, sandbox)` - Get sandbox behavioral analysis
  206. **Note:** Requires `PURPLEMCP_VT_API_KEY` environment variable with a valid VirusTotal API key.
  207. ## Environment Variables
  208. ### Required
  209. - `PURPLEMCP_CONSOLE_TOKEN` - Authentication token (Service User token or Console API token)
  210. - `PURPLEMCP_CONSOLE_BASE_URL` - Console URL (e.g., https://console.sentinelone.net)
  211. ### Optional
  212. - `PURPLEMCP_SDL_BASE_URL` - Dedicated base URL for the SDL API
  213. - When set, this URL is used directly instead of `PURPLEMCP_CONSOLE_BASE_URL` + `/sdl`
  214. - Example: `https://your-dedicated-sdl-endpoint.sentinelone.net`
  215. - When not set, the SDL API is accessed at `{PURPLEMCP_CONSOLE_BASE_URL}/sdl` (default behavior)
  216. - `PURPLEMCP_VT_API_KEY` - VirusTotal API key for threat intelligence tools (get one from
  217. https://www.virustotal.com/gui/my-apikey)
  218. - `PURPLEMCP_SDL_CONSOLE_ACCOUNT_IDS` - Account IDs for SDL query scoping (comma-separated or JSON
  219. array)
  220. - When specified: queries are scoped to the provided account(s)
  221. - When not specified: queries all accounts accessible to the token
  222. - Example: `"426418030212073761"` or `"123,456,789"` or `["123", "456"]`
  223. - `PURPLEMCP_SDL_CONSOLE_SITE_IDS` - Site IDs for SDL query scoping
  224. - When specified: queries are scoped to the provided site
  225. - Requires `PURPLEMCP_SDL_CONSOLE_ACCOUNT_IDS` to also be set with exactly one account ID
  226. - Example: `"1234567890123456789"` or `"123,456,789"` or `"[123, 456]"`
  227. - **Note:** Currently, only the first site ID is used.
  228. - `PURPLEMCP_TRANSPORT_MODE` - MCP transport mode: `stdio`, `http`, `streamable-http`, or `sse`
  229. (default: `stdio`)
  230. - `PURPLEMCP_STATELESS_HTTP` - Enable stateless HTTP mode for serverless deployments (e.g., Amazon
  231. Bedrock AgentCore) - see [deployment guide](deploy/aws_agentcore/BEDROCK_AGENTCORE_DEPLOYMENT.md)
  232. ## Development
  233. We welcome your pull requests or issue submissions.
  234. ### Setup
  235. ```bash
  236. # Install all dependencies
  237. uv sync --all-groups
  238. # Format and lint
  239. uv run ruff format
  240. uv run ruff check .
  241. uv run mypy src tests
  242. ```
  243. ### Testing
  244. ```bash
  245. # Run unit tests
  246. uv run pytest tests/unit/ -v
  247. # Run integration tests (requires .env.test with real credentials)
  248. uv run pytest tests/integration/ -v
  249. # All tests with coverage
  250. uv run pytest --cov=src/purple_mcp --cov-report=html
  251. ```
  252. ### Env-vars for integration-testing of Account Scopes
  253. There are some integration tests that require additional configuration to run (if left unconfigured
  254. they will be skipped). If you want to run
  255. [test_sdl_scope_integration.py](tests/integration/test_sdl_scope_integration.py) you will need to
  256. define the following env-vars in your `.env.test` file (with the dummy values replaced for your
  257. test scenario):
  258. # An accessible account for your console token:
  259. PURPLEMCP_SDL_CONSOLE_ACCOUNT_IDS=123456789012345678
  260. # Another account from your console
  261. PURPLEMCP_SDL_INT_TEST_SECOND_ACCOUNT_ID=222333444555666
  262. # An Agent UUID accessible in your primary account:
  263. PURPLEMCP_SDL_INT_TEST_AGENT_UUID=aaabbb-1234-5678-ccdd-678e89100bb1
  264. # A timestamp at the middle of a 10-minute window where you expect to see events from the Agent UUID:
  265. PURPLEMCP_SDL_INT_TEST_AGENT_EVENT_TIMESTAMP=2025-11-18T05:25:00+00:00
  266. ## Troubleshooting
  267. - **Authentication errors**: Check your token has Account/Site level permissions (not Global), and
  268. your token has not expired
  269. - **PowerQuery does not return expected results**: Check your token has Account/Site level
  270. permissions (not Global)
  271. - **Connection failures**: Verify your console URL and network access; use `--verbose` for debug
  272. logs
  273. ## License
  274. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  275. ## Support
  276. This project is open source and community-driven. Although it is not an official SentinelOne
  277. product, it is maintained by SentinelOne in partnership with the broader open source developer
  278. community. See our [LICENSE](LICENSE) file for further information.
  279. For SentinelOne platform support, use the appropriate
  280. [support channel](https://www.sentinelone.com/global-services/get-support-now/).

Ratings and comments

Sign in to rate this skill.

Sign in

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