{"id":35094188,"url":"https://github.com/Sentinel-One/purple-mcp","last_synced_at":"2026-01-07T10:02:52.393Z","repository":{"id":322672691,"uuid":"1051212126","full_name":"Sentinel-One/purple-mcp","owner":"Sentinel-One","description":"Access SentinelOne's Purple AI and security services through the Model Context Protocol (MCP) - query alerts, vulnerabilities, misconfigurations, and inventory","archived":false,"fork":false,"pushed_at":"2025-11-25T17:15:17.000Z","size":619,"stargazers_count":44,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-28T22:33:12.163Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://s1.ai/purple","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sentinel-One.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-05T16:05:44.000Z","updated_at":"2025-11-27T09:38:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"154fb629-0455-4566-9b35-46f8f5bd4c44","html_url":"https://github.com/Sentinel-One/purple-mcp","commit_stats":null,"previous_names":["sentinel-one/purple-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Sentinel-One/purple-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sentinel-One%2Fpurple-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sentinel-One%2Fpurple-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sentinel-One%2Fpurple-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sentinel-One%2Fpurple-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sentinel-One","download_url":"https://codeload.github.com/Sentinel-One/purple-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sentinel-One%2Fpurple-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28234560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-07T02:00:05.975Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-27T15:04:24.313Z","updated_at":"2026-01-07T10:02:52.388Z","avatar_url":"https://github.com/Sentinel-One.png","language":"Python","funding_links":[],"categories":["📚 Projects (1974 total)"],"sub_categories":["MCP Servers"],"readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://www.sentinelone.com/wp-content/themes/sentinelone/assets/svg/header-logo-light.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://www.sentinelone.com/wp-content/themes/sentinelone/assets/svg/header-logo-dark.svg\"\u003e\n  \u003cimg alt=\"Logo description\" src=\"light-logo.png\"\u003e\n\u003c/picture\u003e\n\n# Purple AI MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nPurple AI MCP Server allows you to access SentinelOne Services with any MCP client.\n\n## Features\n\nThis server exposes SentinelOne's platform through the Model Context Protocol:\n\n- **Purple AI**: Ask security questions, investigate threats\n- **Events**: Run PowerQueries on events in your SentinelOne data lake\n- **Alerts**: Query, search, and investigate alerts\n- **Vulnerabilities**: Track CVEs and security findings\n- **Misconfigurations**: Analyze security posture issues\n- **Inventory**: Ask questions about endpoints, cloud resources, identities, and network devices\n\nPurple AI MCP is a read-only service - you cannot make changes to your account or any objects within your account from this MCP.\n\n## Quick Start\n\n### Using uv (Recommended for Local Development or Deployment)\n\n```bash\n# Install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Set credentials\nexport PURPLEMCP_CONSOLE_TOKEN=\"your_token\"\nexport PURPLEMCP_CONSOLE_BASE_URL=\"https://your-console.sentinelone.net\"\n\n# Run\nuvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode=stdio\n```\n\n### Using Docker\n\n```bash\n# Build the image\ndocker build -t purple-mcp:latest .\n\n# Run with your credentials\nexport PURPLEMCP_CONSOLE_TOKEN=\"your_token\"\nexport PURPLEMCP_CONSOLE_BASE_URL=\"https://your-console.sentinelone.net\"\n\ndocker run -p 8000:8000 \\\n  -e PURPLEMCP_CONSOLE_TOKEN \\\n  -e PURPLEMCP_CONSOLE_BASE_URL \\\n  -e MCP_MODE=streamable-http \\\n  purple-mcp:latest\n```\n\n### Using Amazon Bedrock AgentCore\n```bash\n# Subscribe to Purple AI MCP Server via AWS Marketplace\n\n#Prepare Environment Variables\nPURPLEMCP_CONSOLE_BASE_URL=https://your-console.sentinelone.net\nPURPLEMCP_CONSOLE_TOKEN=your-token\nMCP_MODE=streamable-http \nPURPLEMCP_STATELESS_HTTP=True\n```\nFollow instructions for Amazon Bedrock AgentCore Deployment [here](BEDROCK_AGENTCORE_DEPLOYMENT.md)\n\n### Using Amazon Elastic Container Service (ECS)\n```bash\n# Subscribe to Purple AI MCP Server via AWS Marketplace\n\n#Prepare Environment Variables\nPURPLEMCP_CONSOLE_BASE_URL=https://your-console.sentinelone.net\nPURPLEMCP_CONSOLE_TOKEN=your-token\nMCP_MODE=streamable-http \nPURPLEMCP_STATELESS_HTTP=True\n```\nFollow instructions for Amazon Elastic Container Service Deployment [here](AMAZON_ECS_DEPLOYMENT.md)\n\n\nFor production deployments, see [Deployment Guide](DOCKER.md).\n\n**Note:** Purple AI MCP does not include built-in authentication. For network-exposed deployments, place it behind a reverse proxy or load balancer. See [Production Setup](PRODUCTION_SETUP.md) for cloud load balancer configurations (AWS ALB, GCP Cloud Load Balancing, Azure Application Gateway) or nginx examples for self-hosted deployments.\n\n---\n\nYour token needs Account or Site level permissions (not Global). Get one from Policy \u0026 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.\n\n## Clients\n\nPurple AI MCP supports `stdio`, `sse`, and `streamable-http` protocols and should work in any client that supports MCP.  Some sample configurations are listed below.\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"purple-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/Sentinel-One/purple-mcp.git\", \"purple-mcp\", \"--mode\", \"stdio\"],\n      \"env\": {\n        \"PURPLEMCP_CONSOLE_TOKEN\": \"your_token\",\n        \"PURPLEMCP_CONSOLE_BASE_URL\": \"https://your-console.sentinelone.net\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\nRun this command in a terminal:\n\n`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`\n\n### OpenAI Codex\n\nRun this command in a terminal:\n\n`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`\n\n### Pydantic AI\n\nHere is some example Python code to use Purple MCP with a Pydantic AI Agent.\n\n```python\nfrom pydantic_ai import Agent\nfrom pydantic_ai.mcp import MCPServerStdio\n\nserver = MCPServerStdio(\n    'uvx', args=[\"--from\", \"git+https://github.com/Sentinel-One/purple-mcp.git\", \"purple-mcp\", \"--mode\", \"stdio\"], timeout=10\n)\nagent = Agent('anthropic:claude-haiku-4-5', toolsets=[server])\n```\n\n### Zed\n\nEdit `~/.zed/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"purple-mcp\": {\n      \"enabled\": true,\n      \"source\": \"custom\",\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/Sentinel-One/purple-mcp.git\", \"purple-mcp\", \"--mode\", \"stdio\"],\n      \"env\": {\n        \"PURPLEMCP_CONSOLE_TOKEN\": \"your_token\",\n        \"PURPLEMCP_CONSOLE_BASE_URL\": \"https://your-console.sentinelone.net\"\n      }\n    }\n  }\n}\n```\n\n### Other Clients\n\nFor debugging or to host server for multiple clients, run in streamable-http mode and connect via mcp-remote:\n\n```bash\n# Terminal 1: Start server\nexport PURPLEMCP_CONSOLE_TOKEN=\"your_token\"\nexport PURPLEMCP_CONSOLE_BASE_URL=\"https://your-console.sentinelone.net\"\nuvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode streamable-http --host localhost --port 8000\n\n# Terminal 2: Connect with any client\nnpx -y mcp-remote http://127.0.0.1:8000/mcp\n```\n\nWe suggest you **do not** expose Purple AI MCP on a network at this time, as there is no authentication enforced and anyone could access a configured SentinelOne account.\n\n## Available Tools\n\n### Purple AI\n- `purple_ai(query)` - Ask security questions\n\n### Data Lake\n- `powerquery(query, start_time, end_time)` - Run PowerQuery analytics\n\n### Alerts\n- `get_alert(alert_id)` - Get alert details\n- `list_alerts(first, after, view_type)` - List recent alerts\n- `search_alerts(filters, first)` - Search with filters\n- `get_alert_notes(alert_id)` - Get alert comments\n- `get_alert_history(alert_id)` - View alert timeline\n\n### Vulnerabilities\n- `get_vulnerability(id)` - Get vulnerability details\n- `list_vulnerabilities(first, after)` - List recent vulnerabilities\n- `search_vulnerabilities(filters, first)` - Search CVEs and findings\n- `get_vulnerability_notes(id)` - Get comments\n- `get_vulnerability_history(id)` - View timeline\n\n### Misconfigurations\n- `get_misconfiguration(id)` - Get misconfiguration details\n- `list_misconfigurations(first, after)` - List recent issues\n- `search_misconfigurations(filters, first)` - Search by criteria\n- `get_misconfiguration_notes(id)` - Get comments\n- `get_misconfiguration_history(id)` - View timeline\n\n### Asset Inventory\n- `get_inventory_item(item_id)` - Get asset details\n- `list_inventory_items(limit, skip, surface)` - List assets by surface type\n- `search_inventory_items(filters, limit)` - Search with advanced filters\n\n## Environment Variables\n- `PURPLEMCP_CONSOLE_TOKEN` - Service user token (Account or Site level)\n- `PURPLEMCP_CONSOLE_BASE_URL` - Console URL (e.g., https://console.sentinelone.net)\n- `PURPLEMCP_TRANSPORT_MODE` - MCP transport mode: `stdio` (default), `sse`, or `streamable-http`\n- `PURPLEMCP_STATELESS_HTTP` - Enable stateless HTTP mode for serverless deployments (e.g., Amazon Bedrock AgentCore) - see [deployment guide](BEDROCK_AGENTCORE_DEPLOYMENT.md)\n\n\n## Development\n\nWe welcome your pull requests or issue submissions.\n\n### Setup\n\n```bash\n# Install all dependencies\nuv sync --group dev --group test\n\n# Format and lint\nuv run ruff format\nuv run ruff check\nuv run mypy\n```\n\n### Testing\n\n```bash\n# Run unit tests\nuv run pytest tests/unit/ -v\n\n# Run integration tests (requires .env.test with real credentials)\nuv run pytest tests/integration/ -v\n\n# All tests with coverage\nuv run pytest --cov=src/purple_mcp --cov-report=html\n```\n\n## Troubleshooting\n\n  * **Authentication errors**: Check your token has Account/Site level permissions (not Global), and your token has not expired\n  * **PowerQuery does not return expected results**: Check your token has Account/Site level permissions (not Global)\n  * **Connection failures**: Verify your console URL and network access; use `--verbose` for debug logs\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor issues with this MCP server, [open an issue](https://github.com/Sentinel-One/purple-mcp/issues).\n\nThis project is open source and community-driven. Although it is not an official SentinelOne product, it is maintained by SentinelOne in partnership with the broader open source developer community.  See our [LICENSE](LICENSE) file for further information.\n\nFor SentinelOne platform support, use the appropriate [support channel](https://www.sentinelone.com/global-services/get-support-now/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSentinel-One%2Fpurple-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSentinel-One%2Fpurple-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSentinel-One%2Fpurple-mcp/lists"}