Wazuh MCP Server

---

What This Does

Your Wazuh SIEM generates thousands of alerts, vulnerability findings, and agent events daily. Investigating them means juggling dashboards, writing API queries, and manually correlating data across tools.

This MCP server turns that workflow into a conversation:

You:    "Show me critical alerts from the last hour"
AI:     [calls get_wazuh_alerts] Found 3 critical alerts:
        1. SSH brute force from 10.0.1.45 → agent-003 (Rule 5712, Level 10)
        2. Rootkit detection on agent-007 (Rule 510, Level 12)
        3. FIM change /etc/shadow on agent-001 (Rule 550, Level 10)

You:    "Block that source IP on agent-003"
AI:     [calls wazuh_block_ip] Blocked 10.0.1.45 via firewall-drop on agent-003.

You:    "Which agents have unpatched critical CVEs?"
AI:     [calls get_wazuh_critical_vulnerabilities] 3 agents with critical vulnerabilities...

It works with Claude Desktop, Open WebUI + Ollama (fully local, air-gapped), mcphost, or any MCP-compliant client.

---

Works With Cloud AND Local LLMs

This is a standard MCP tool server. It doesn't care what LLM you use — it just executes tools and returns results.

Mode	LLM	Client	Data leaves your network?
Cloud	Claude, GPT, etc.	Claude Desktop, any MCP client	Yes (to LLM provider)
Local	Llama, Qwen, Mistral via Ollama	Open WebUI, mcphost, IBM/mcp-cli	No. Fully air-gappable.

For security teams that can't send SIEM data to cloud APIs (compliance, air-gapped networks, data sovereignty), the local mode with Ollama keeps everything on-premises. Both modes coexist — same server, same tools, same API.

Quick Start: Local LLM with mcphost

# 1. Start the MCP server
docker compose up -d

# 2. Install mcphost (Go binary, no dependencies)
go install github.com/mark3labs/mcphost@latest

# 3. Configure
cat > ~/.mcphost.yml << 'EOF'
mcpServers:
  wazuh:
    type: remote
    url: http://localhost:3000/mcp
    headers: ["Authorization: Bearer ${env://MCP_API_KEY}"]
EOF

# 4. Chat with your SIEM using a local model
export MCP_API_KEY="your-key-from-server-logs"
mcphost --model ollama/qwen2.5:7b

Quick Start: Multi-User SOC with Open WebUI

Open WebUI v0.6.31+ connects to our /mcp endpoint natively. Add it as an MCP tool server in Admin Settings, and your entire team gets AI-powered SIEM analysis with conversation history, RBAC, and a web UI.

---

55 Security Tools

Every tool is validated, rate-limited, scope-checked, and audit-logged.

Category	Tools	What They Do
Alerts (5)	get_wazuh_alerts get_wazuh_alert_summary get_alerts_aggregated analyze_alert_patterns search_security_events	Query, filter, search, and aggregate alert data via the Indexer. Timestamps accept ISO 8601 or relative date math (now-24h); get_alerts_aggregated summarizes a whole period with no document limit
Agents (6)	get_wazuh_agents get_wazuh_running_agents check_agent_health get_agent_processes get_agent_ports get_agent_configuration	Monitor agent status, running processes, open ports, and configs
Vulnerabilities (3)	get_wazuh_vulnerabilities get_wazuh_critical_vulnerabilities get_wazuh_vulnerability_summary	Query CVEs by severity, agent, and package
Security Analysis (6)	analyze_security_threat check_ioc_reputation search_external_context perform_risk_assessment get_top_security_threats generate_security_report	Threat analysis, IOC lookup, optional web context, risk scoring, security reports
Compliance (6)	run_compliance_check get_iso27001_dashboard get_iso27001_control_detail get_iso27001_gap_analysis get_iso27001_alerts get_sca_policy_checks	Compliance scoring for PCI-DSS, HIPAA, SOX, GDPR, NIST, and ISO 27001:2022 (Annex A control mapping, gap analysis, SCA detail)
System (10)	get_wazuh_statistics get_wazuh_cluster_health get_wazuh_cluster_nodes get_wazuh_rules_summary search_wazuh_manager_logs get_wazuh_manager_error_logs get_wazuh_log_collector_stats get_wazuh_remoted_stats get_wazuh_weekly_stats validate_wazuh_connection	Cluster health, rules, manager logs, stats, connectivity
Active Response (9)	wazuh_block_ip wazuh_isolate_host wazuh_kill_process wazuh_disable_user wazuh_quarantine_file wazuh_firewall_drop wazuh_host_deny wazuh_active_response wazuh_restart	Block IPs, isolate hosts, kill processes, quarantine files
Verification (5)	wazuh_check_blocked_ip wazuh_check_agent_isolation wazuh_check_process wazuh_check_user_status wazuh_check_file_quarantine	Verify active response actions took effect
Rollback (5)	wazuh_unisolate_host wazuh_enable_user wazuh_restore_file wazuh_firewall_allow wazuh_host_allow	Undo active response actions

The 14 state-changing tools (Active Response + Rollback) require the wazuh:write scope; everything else needs only wazuh:read. ISO 27001 also adds an iso27001_assessment guided prompt (5 prompts total).

---

Quick Start

Prerequisites

• Docker 20.10+ with Compose v2
• Wazuh 4.8.0–4.14.7 with API access enabled

Deploy

git clone https://github.com/gensecaihq/Wazuh-MCP-Server.git
cd Wazuh-MCP-Server
cp .env.example .env

Edit .env:

WAZUH_HOST=your-wazuh-server
WAZUH_USER=your-api-user
WAZUH_PASS=your-api-password

docker compose up -d
curl http://localhost:3000/health

Pre-built image

A multi-arch image (amd64/arm64) is published to GitHub Container Registry on every release and on every push to main:

docker pull ghcr.io/gensecaihq/wazuh-mcp-server:latest   # main branch
docker pull ghcr.io/gensecaihq/wazuh-mcp-server:4.3.0    # pinned release

docker run -d --name wazuh-mcp-server --env-file .env -p 3000:3000 \
  ghcr.io/gensecaihq/wazuh-mcp-server:latest

Connect Claude Desktop

1. Settings → Connectors → Add custom connector
2. URL: https://your-server/mcp
3. Add Bearer token in Advanced settings

Detailed setup: Claude Integration Guide

---

Security

This server sits between an LLM and your SIEM. Security is not optional.

Layer	What It Does
RBAC	Per-tool scope enforcement, fail-closed: a token with no scope claim gets read-only, never write. The 14 state-changing tools (active response + rollback) require wazuh:write, which is opt-in (MCP_API_KEY_SCOPES="wazuh:read wazuh:write"). Authless mode is read-only unless AUTHLESS_ALLOW_WRITE=true.
Audit Logging	Every destructive tool call (block IP, isolate host, kill process) is logged with client ID, session, timestamp, and full arguments.
Output Sanitization	Credentials, tokens, and API keys in alert full_log fields are redacted before reaching the LLM. Prevents credential leakage through AI responses.
Input Validation	Every parameter validated: regex agent IDs, ipaddress module for IPs, shell metacharacter blocking for active response, Elasticsearch Query DSL (no string interpolation).
Rate Limiting	Per-principal sliding window (keyed on the authenticated client + trusted-proxy IP), with a short retry-after backoff — seconds until the oldest request leaves the window, not a fixed multi-minute block.
Circuit Breakers	Wazuh API failures trigger fail-fast for 60s, auto-recover. Single trial in HALF_OPEN state.
Log Sanitization	Global filter redacts passwords, tokens, secrets from all server logs.
Container Hardening	Non-root user, read-only filesystem, CAP_DROP ALL, no-new-privileges.

# Generate a secure API key
python -c "import secrets; print('wazuh_' + secrets.token_urlsafe(32))"

---

Configuration

Required

Variable	Description
WAZUH_HOST	Wazuh Manager hostname or IP
WAZUH_USER	API username
WAZUH_PASS	API password

Optional

Variable	Default	Description
ENVIRONMENT	development	production enforces stricter checks (see below)
WAZUH_PORT	55000	Manager API port
WAZUH_VERIFY_SSL	true	Verify the Manager's TLS certificate
MCP_HOST	0.0.0.0	Server bind address
MCP_PORT	3000	Server port
AUTH_MODE	bearer	oauth, bearer, or none
AUTH_SECRET_KEY	auto (dev only)	JWT signing key. Required when ENVIRONMENT=production (the server refuses to start without it) — set the same value on every instance
MCP_API_KEY	auto (dev only)	Pre-set API key (wazuh_…)
MCP_API_KEY_SCOPES	wazuh:read	Scopes for MCP_API_KEY. Add wazuh:write to enable active-response tools
AUTHLESS_ALLOW_WRITE	false	Allow active response in authless mode
ALLOWED_ORIGINS	https://claude.ai,...	CORS origins (comma-separated)
TRUSTED_PROXIES	—	Proxy IPs to trust for X-Forwarded-For (correct per-client rate limiting behind a proxy)
REDIS_URL	—	Redis URL for multi-instance session storage
RESPONSE_FORMAT	json	Wire format for alert/event/vulnerability results: json or gcf (see below)

Response encoding (GCF)

Alert, security-event, and vulnerability tools return uniform record collections under a data.affected_items array. Setting RESPONSE_FORMAT=gcf encodes those responses as a Graph Compact Format generic wire instead of JSON, factoring the repeated field names into a single header so the response uses fewer tokens when it crosses the LLM boundary.

It is opt-in, lossless, and every response stays complete (a format change only, no cross-turn deduplication, so no alert is ever omitted). If encoding fails — or the encoder isn't installed — the tool falls back to JSON. It composes with the existing compact field-projection parameter.

The encoder is one zero-dependency package (pinned exact). Install it directly, or via the gcf extra from a source checkout:

pip install gcf-python==2.5.1        # direct
pip install ".[gcf]"                 # or, from a clone of this repo

Production note: the server listens over plain HTTP — terminate TLS at a reverse proxy or load balancer. OAuth knobs (OAUTH_ENABLE_DCR — off by default, OAUTH_*_TTL) and rate-limit tuning (RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW) are in the Configuration Guide.

Wazuh Indexer (for alert search + vulnerabilities)

Variable	Default	Description
WAZUH_INDEXER_HOST	—	Indexer hostname (an http:// prefix selects plain HTTP)
WAZUH_INDEXER_PORT	9200	Indexer port
WAZUH_INDEXER_USER	—	Indexer username
WAZUH_INDEXER_PASS	—	Indexer password
WAZUH_INDEXER_SSL	true	Use HTTPS for the Indexer (set false for a plain-HTTP OpenSearch node)
WAZUH_INDEXER_VERIFY_SSL	true	Verify the Indexer's TLS certificate
YDC_API_KEY	—	Optional You.com API key. Enables the search_external_context tool
YDC_BASE_URL	https://ydc-index.io	Optional You.com Search API base URL
YDC_VERIFY_SSL	true	Verify You.com TLS certificates independently of Wazuh
WAZUH_CLUSTERS_FILE	./config/clusters.json	Optional multi-cluster topology file (see below)
WAZUH_AR_FIREWALL_UNDO_COMMAND	—	Custom active-response command that removes a firewall-drop block. Required for wazuh_firewall_allow — stock Wazuh can't unblock via the API
WAZUH_AR_HOSTDENY_UNDO_COMMAND	—	Custom active-response command that removes a hosts.deny block. Required for wazuh_host_allow

Full reference: Configuration Guide

Multi-Cluster (optional)

Managing several Wazuh deployments? Drop a clusters.json next to your config (see config/clusters.json.example) and every tool gains an optional cluster_id argument plus a list_wazuh_clusters tool:

• No clusters.json → single-cluster behavior from env vars, exactly as before.
• With clusters.json → named clusters, each with its own Manager (and optionally Indexer) credentials; "${ENV_VAR}" values are resolved from the environment so secrets stay out of the file. The env-configured cluster remains reachable as default.
• Cross-Cluster Search → point clusters at a shared OpenSearch CCS coordinator and set ccs_prefix (the remote-cluster name); alert/vulnerability queries become eu:wazuh-alerts-*. An entry with "ccs_prefix": "*" gives you an all pseudo-cluster that searches every remote cluster at once.

---

API Endpoints

Endpoint	Method	Description
/mcp	POST/GET/DELETE	MCP Streamable HTTP (recommended)
/sse	GET	Legacy Server-Sent Events
/health	GET	Liveness probe — 200 while the process is up (no dependency checks; use for the container healthcheck)
/ready	GET	Readiness probe — checks Wazuh Manager/Indexer reachability; 503 when a dependency is down
/metrics	GET	Prometheus metrics
/auth/token	POST	Exchange API key for JWT (bearer mode)
/.well-known/oauth-authorization-server	GET	OAuth 2.0 discovery (oauth mode)
/.well-known/oauth-protected-resource	GET	OAuth protected-resource metadata, RFC 9728 (oauth mode)
/docs	GET	OpenAPI documentation

---

Architecture

src/wazuh_mcp_server/
├── server.py           # MCP protocol + 55 tool handlers
├── config.py           # Environment-based configuration
├── auth.py             # JWT + API key authentication
├── oauth.py            # OAuth 2.0 with Dynamic Client Registration
├── security.py         # Rate limiting, CORS, input validation
├── monitoring.py       # Prometheus metrics, structured logging
├── resilience.py       # Circuit breakers, retries, graceful shutdown
├── session_store.py    # Pluggable sessions (in-memory + Redis)
└── api/
    ├── wazuh_client.py    # Wazuh Manager REST API client
    └── wazuh_indexer.py   # Wazuh Indexer (Elasticsearch) client

---

Take It Further: Autonomous Agentic SOC

Combine this MCP server with Wazuh Autopilot to build an agentic Security Operations Center.

While this server gives you conversational access to Wazuh, Autopilot runs an eleven-agent AI SOC team on top of it around the clock — a seven-stage reactive pipeline (triage → correlation → investigation → response) plus four proactive specialists (vulnerability management, threat intel, threat hunting, detection engineering). Every containment action is gated behind two-tier human approval. Runs on OpenClaw, Hermes, or NVIDIA NemoClaw.

Manual SOC:    Alert → Analyst reviews → Hours → Response
Agentic SOC:   Alert → AI triages → Seconds → Response ready for approval

Explore Wazuh Autopilot

---

Documentation

Guide	Description
Claude Integration	Claude Desktop setup and authentication
Configuration	Full configuration reference
Advanced Features	HA, serverless, compact mode
API Documentation	Per-tool documentation
Security	Security hardening guide
Troubleshooting	Common issues and solutions
Operations	Deployment, monitoring, maintenance

---

Contributing

We welcome contributions. See Issues for bugs and feature requests, Discussions for questions.

---

License

MIT

---

Acknowledgments

• Wazuh — Open source security platform
• Model Context Protocol — AI tool integration standard
• Ollama — Local LLM inference
• Open WebUI — Self-hosted AI chat interface
• mcphost — MCP CLI host with LLM support

---

Contributors

Contributors

Avatar	Username	Contributions
	@alokemajumder	💻 Code, 🐛 Issues, 🔀 PRs, 💬 Discussions
	@Karibusan	💻 Code, 🐛 Issues, 🔀 PRs
	@gensecai-dev	💻 Code, 🔀 PRs, 💬 Discussions
	@aiunmukto	💻 Code, 🔀 PRs
	@andrzej-piotrowski-pl	💻 Code, 🔀 PRs
	@kanylbullen	💻 Code, 🔀 PRs
	@lucascruzb	💻 Code, 🔀 PRs
	@lwsinclair	💻 Code, 🔀 PRs
	@mouse-value-add	💻 Code, 🔀 PRs
	@SiM22	💻 Code, 🔀 PRs
	@blackwell-systems	🔀 PRs
	@DrRSatzteil	🔀 PRs
	@MilkyWay88	🔀 PRs
	@taylorwalton	🔀 PRs
	@cbassonbgroup	🐛 Issues
	@cybersentinel-06	🐛 Issues
	@daod-arshad	🐛 Issues
	@mamema	🐛 Issues
	@marcolinux46	🐛 Issues
	@matveevandrey	🐛 Issues
	@punkpeye	🐛 Issues
	@tonyliu9189	🐛 Issues
	@Uberkarhu	🐛 Issues
	@bl4ck5w4n07	💬 Discussions
	@gnix45	💬 Discussions
	@hackdefendr	💬 Discussions
	@melmasry1987	💬 Discussions
	@Vasanth120v	💬 Discussions
	@wqfh	💬 Discussions

Legend: 💻 Code · 🐛 Issues · 🔀 Pull Requests · 💬 Discussions

Auto-updated by GitHub Actions