Crowdsentinel MCP Server

CrowdSentinel MCP Server

AI-Powered Threat Hunting & Incident Response Framework

MCP Official Registry · PyPI Package

Open-source threat hunting orchestrator connecting LLMs to enterprise security data via Model Context Protocol (MCP)

Quick Start · Installation · CLI Usage · Features · Architecture · Documentation · Examples

Warning

This project is in active development and intended for security testing, research, and educational purposes only. It is not production-ready. Do not deploy in production environments. APIs, tool interfaces, and data formats may change without notice. Use at your own risk.

---

Demo

https://github.com/user-attachments/assets/0d0381f0-5b68-43b2-8630-19ec130885b2

---

What is CrowdSentinel?

CrowdSentinel transforms traditional SIEM querying into intelligent, framework-driven investigations using natural language. It serves as a unified security intelligence layer that connects large language models to enterprise security data sources, enabling:

• Natural Language Threat Hunting — Query Elasticsearch using plain English
• AI-Guided Investigation Workflows — Built-in prompts guide agents through proper IR methodology
• Persistent Investigation State — Memory-managed IoC tracking, forensic timelines, and cross-query correlation that survives across sessions (8GB FIFO storage)
• Cross-Tool IoC Correlation — IoCs discovered in one tool are automatically available to all others
• Multi-Source Analysis — Elasticsearch, EVTX logs (Chainsaw), PCAP files (Wireshark), live endpoint forensics (Velociraptor), local host forensics (osquery)
• Velociraptor Endpoint Forensics — 25 MCP tools for live artefact collection (processes, network, persistence, execution evidence, NTFS MFT, SRUM, remote EVTX) with automatic IoC extraction
• Encoded-Command Deobfuscation — Automatically peels base64/UTF-16LE/gzip/hex layers off encoded commands (e.g. PowerShell -EncodedCommand) so C2 addresses hidden inside them surface as IoCs
• Adaptive Schema Intelligence — Data-driven schema registry (ECS, Sysmon, Windows Security, auditd, Zeek, Packetbeat, AWS CloudTrail) adapts hunts to each index's field conventions
• DFIR Knowledge Resources — 9 MCP resources exposing investigation playbooks, Pyramid of Pain reference, and cross-correlation guidance directly to connected AI agents
• Standalone CLI — Full threat hunting from the terminal without an MCP client

---

Installation

Install from PyPI (recommended)

# Install with pip

pip install crowdsentinel-mcp-server

Or install with uv

uv pip install crowdsentinel-mcp-server

Download detection rules, Chainsaw, and Sigma rules (one-time)

crowdsentinel setup

Validate connector configuration and readiness (offline, no external calls)

crowdsentinel doctor

Optional extras:

# Velociraptor live endpoint forensics (adds 25 MCP tools)

pip install 'crowdsentinel-mcp-server[velociraptor]'

Long-tail deobfuscation coverage via chepy (XOR, exotic encodings).

The stdlib decoder core works without this — chepy only extends it.

pip install 'crowdsentinel-mcp-server[deobf]'

Detection rules (6,060 Lucene + EQL + ES|QL) are bundled with the package — no download needed. The setup command downloads additional tools:

• Chainsaw binary for EVTX analysis
• 3,000+ Sigma rules for Chainsaw

Downloaded tools are stored in ~/.crowdsentinel/ and persist across package upgrades.

System dependency for PCAP analysis:

# Required for network traffic analysis and cross-tool IoC correlation

sudo apt install tshark # Debian/Ubuntu/Kali sudo dnf install wireshark-cli # Fedora/RHEL brew install wireshark # macOS

Run directly with uvx (no install needed)

# Elasticsearch 8.x (default)

uvx crowdsentinel-mcp-server

Other backends

uvx crowdsentinel-mcp-server-es7 # Elasticsearch 7.x uvx crowdsentinel-mcp-server-es9 # Elasticsearch 9.x uvx opensearch-mcp-server # OpenSearch 1.x/2.x/3.x

Install from source

git clone https://github.com/thomasxm/CrowdSentinels-AI-MCP.git

cd CrowdSentinels-AI-MCP chmod +x setup.sh && ./setup.sh

Or install everything, including all optional extras (deobf/chepy, velociraptor)

./setup.sh --full

The setup script will:

• Install dependencies (pipx, uv, Claude Code CLI if needed)
• Bundle 6,060 detection rules and download Chainsaw binary
• Prompt for Elasticsearch credentials (never hardcoded)
• Configure the MCP server with Claude Code
• Validate your connection

With --full, every optional extra is installed too, so all 139 MCP tools have their dependencies available — the recommended mode for a production-ready server.

Installed Size

CrowdSentinel bundles 6,060 detection rules and integrates with external analysis tools. Below is the full disk space breakdown so you can plan accordingly.

Core package (via `pip` or `uvx`):

Additional tools (via `crowdsentinel setup`):

System dependency (via package manager):

Full installation summary:

Note: PyPI download size is only 8.9 MB (wheel) thanks to compression of the bundled detection rules.

---

Quick Start

1. Set environment variables

export ELASTICSEARCH_HOSTS="https://localhost:9200"

export ELASTICSEARCH_API_KEY="your_api_key"

Or use username/password:

export ELASTICSEARCH_USERNAME="elastic"

export ELASTICSEARCH_PASSWORD="your_password"

export VERIFY_CERTS="false"

2. Connect to an MCP Client

CrowdSentinel works with any MCP-compatible AI agent. Choose your client below:

Claude Code (CLI)

claude mcp add crowdsentinel \

-e ELASTICSEARCH_HOSTS="https://localhost:9200" \ -e ELASTICSEARCH_API_KEY="your_api_key" \ -e VERIFY_CERTS="false" \ -- uvx crowdsentinel-mcp-server

</details>

Claude Desktop

Edit ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{

"mcpServers": { "crowdsentinel": { "command": "uvx", "args": ["crowdsentinel-mcp-server"], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_API_KEY": "your_api_key", "VERIFY_CERTS": "false" } } } }

</details>

VS Code Copilot

Create .vscode/mcp.json in your workspace:

{

"servers": { "crowdsentinel": { "command": "uvx", "args": ["crowdsentinel-mcp-server"], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_API_KEY": "your_api_key", "VERIFY_CERTS": "false" } } } }

Then enable MCP in VS Code settings: "chat.mcp.enabled": true

Cursor

Create or edit ~/.cursor/mcp.json:

{

"mcpServers": { "crowdsentinel": { "command": "uvx", "args": ["crowdsentinel-mcp-server"], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_API_KEY": "your_api_key", "VERIFY_CERTS": "false" } } } }

</details>

Roo Code (VS Code Extension)

Create .roo/mcp.json in your workspace:

{

"mcpServers": { "crowdsentinel": { "command": "uvx", "args": ["crowdsentinel-mcp-server"], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_API_KEY": "your_api_key", "VERIFY_CERTS": "false" } } } }

Or configure via Roo Code settings panel: Settings > MCP Servers > Add Server.

5ire

In 5ire settings (v0.15.0+), add an MCP server with:

• Command: uvx
• Arguments: crowdsentinel-mcp-server
• Environment Variables:
• ELASTICSEARCH_HOSTS = https://localhost:9200
• ELASTICSEARCH_API_KEY = your_api_key
• VERIFY_CERTS = false

Note: 5ire v0.14.0 has known MCP compatibility issues. Use v0.15.0+ for reliable operation.

Any MCP Client (Generic)

stdio transport (default — works with most clients):

{

"mcpServers": { "crowdsentinel": { "command": "uvx", "args": ["crowdsentinel-mcp-server"], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_API_KEY": "your_api_key", "VERIFY_CERTS": "false" } } } }

SSE transport (for web-based clients):

crowdsentinel-mcp-server --transport sse --port 8001

Connect to: http://localhost:8001/sse/

HTTP transport (for REST API clients):

crowdsentinel-mcp-server --tran