Purple AI MCP Server
by wojtekkura
README.md
# Purple AI MCP Server
Fork of [Sentinel-One/purple-mcp](https://github.com/Sentinel-One/purple-mcp) with added support for storing the API token in the OS credential store (Windows Credential Manager) instead of plaintext configuration files.
## What is Purple AI MCP?
Purple AI MCP is a [Model Context Protocol](https://modelcontextprotocol.io/) server that connects AI clients (Claude Desktop, Cursor, etc.) to SentinelOne's security platform. It gives AI assistants direct access to:
- **Purple AI** — natural language queries against your security data
- **Singularity Data Lake** — run and retrieve SDL queries
- **Alerts** — list, search, and inspect security alerts
- **Vulnerabilities** — query vulnerability findings
- **Misconfigurations** — review cloud and Kubernetes misconfigurations
- **Asset Inventory** — search and explore your asset inventory
By default Purple AI MCP is read-only — it cannot make changes to your SentinelOne account.
See [Write tools](#write-tools-remote-agent-upgrade) for the one opt-in exception.
## Quick Start
### Install uv
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
## Requirements
- [uv](https://docs.astral.sh/uv/) installed
- A SentinelOne Console API token with **Account** or **Site** level permissions (not Global)
- Your SentinelOne console base URL (e.g. `https://usea1-008.sentinelone.net`)
## 1. Store your token in Windows Credential Manager
Run this once in PowerShell:
```powershell
cmdkey /generic:"purple-mcp" /user:"PURPLEMCP_CONSOLE_TOKEN" /pass:"your-token-here"
```
To verify:
```powershell
cmdkey /list:"purple-mcp"
```
To remove:
```powershell
cmdkey /delete:"purple-mcp"
```
## 2. Configure Claude Desktop
Edit `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"purple-mcp": {
"command": "uvx",
"args": [
"--from",
"purple-mcp @ https://github.com/wojtekkura/purple-mcp/archive/refs/heads/main.tar.gz",
"purple-mcp",
"--mode",
"stdio"
],
"env": {
"PURPLEMCP_CONSOLE_BASE_URL": "https://your-console.sentinelone.net"
}
}
}
}
```
Replace `https://your-console.sentinelone.net` with your actual console URL. The token is read automatically from Windows Credential Manager at startup — no token in the config file.
Restart Claude Desktop after saving the file.
## Write tools: remote agent upgrade
Two read-only tools are always available:
- `get_agent_upgrade_options(endpoint)` — current agent version vs. the newest GA package for the endpoint's OS/arch.
- `get_agent_upgrade_status(endpoint)` — current version plus recent upgrade activity.
`upgrade_agent(endpoint, package_id, confirm)` triggers `agents/actions/update-software` and is
**only registered when `PURPLEMCP_ENABLE_WRITE_TOOLS=true`**. It is analyst-confirmed by design:
1. `confirm=false` (default) returns a preview (current version, target version, `package_id`) and changes nothing.
2. After the analyst approves, call again with `confirm=true` and that `package_id`. The agent is
re-checked (still active, still outdated) before the upgrade is sent. The POST is never retried.
The upgrade needs a token whose role allows **Endpoints → Update/Upgrade software**. Use a dedicated
service-user token rather than widening the read token:
```powershell
uvx --from "purple-mcp @ https://github.com/wojtekkura/purple-mcp/archive/refs/heads/main.tar.gz" purple-mcp-store-token --write
```
and add `"PURPLEMCP_ENABLE_WRITE_TOOLS": "true"` to the `env` block above. Without a write token,
the console token is used.
## Path exclusions (disabled by default)
`list_path_exclusions(endpoint, value_contains, include_parents)` is read-only and always available.
`create_path_exclusion(...)` creates an S1 path exclusion on the endpoint's group (or site) with the
same preview → `confirm=true` flow, breadth guard and duplicate check as the SOAR
*Create Path Exclusion* action; the approver, reason and reference are written to the exclusion
description. Exclusions are applied through the SOAR integration for now, so this tool is
**only registered when both `PURPLEMCP_ENABLE_WRITE_TOOLS=true` and
`PURPLEMCP_ENABLE_EXCLUSION_TOOLS=true`**. The write token needs **Exclusions → View/Create**.
## License
MIT — see [LICENSE](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues