Wazuh MCP — AI-Powered Security Operations

Connect Wazuh to Claude AI via the Model Context Protocol (MCP), enabling natural-language security operations directly inside Claude Desktop.

87 tools across 21 domain modules — alerts, vulnerabilities, FIM, compliance, MITRE ATT&CK, threat hunting, active response, fleet inventory, SCA, CDB lists, rules, threat intel, incidents, reporting, notifications, onboarding, cluster health, archive search, and alert suppression.

---

Table of Contents

• Quick Start — Docker
• Quick Start — Local (systemd)
• Connect Claude Desktop
• Environment Variables
• Tool Reference
• MCP Prompts
• Architecture
• Optional Integrations
• Security Considerations
• Common Issues

---

Quick Start — Docker

This is the recommended deployment method. The container bundles all dependencies and exposes the MCP server on port 8000.

1. Clone the repository

git clone https://github.com/adi5353/wazuh-mcp.git
cd wazuh-mcp

2. Create your environment file

cp env.example .env
nano .env

Fill in at minimum:

WAZUH_HOST=https://your-wazuh-manager:55000
WAZUH_USER=wazuh-mcp
WAZUH_PASS=YourPassword

WAZUH_INDEXER_HOST=https://your-wazuh-indexer:9200
WAZUH_INDEXER_USER=wazuh-readonly
WAZUH_INDEXER_PASS=YourPassword

WAZUH_VERIFY_SSL=false
WAZUH_MCP_TRANSPORT=http
WAZUH_MCP_HOST=0.0.0.0
WAZUH_MCP_PORT=8000

3. Start the container

docker compose up -d

4. Verify it’s running

docker compose ps
curl -si http://localhost:8000/sse | head -3
# Expected: HTTP/1.1 200 OK

View logs:

docker compose logs -f wazuh-mcp

Stop and restart:

docker compose down
docker compose up -d

---

Quick Start — Local (systemd)

Use this if you want to run directly on the Wazuh server without Docker.

1. Clone and install

git clone https://github.com/adi5353/wazuh-mcp.git
cd wazuh-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Configure

cp env.example .env
nano .env   # fill in WAZUH_HOST, WAZUH_USER, WAZUH_PASS, indexer credentials

3. Run as a systemd service

sudo tee /etc/systemd/system/wazuh-mcp.service << 'EOF'
[Unit]
Description=Wazuh MCP Server
After=network.target

[Service]
Type=simple
User=vagrant
WorkingDirectory=/home/vagrant/wazuh-mcp
EnvironmentFile=/home/vagrant/wazuh-mcp/.env
ExecStart=/home/vagrant/wazuh-mcp/.venv/bin/python -m wazuh_mcp
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now wazuh-mcp
sudo systemctl status wazuh-mcp

Verify:

ss -tlnp | grep 8000   # must show 0.0.0.0:8000
curl -si http://localhost:8000/sse | head -3

---

Connect Claude Desktop

Option A — HTTP/SSE (Docker or remote server)

Install mcp-remote on the machine running Claude Desktop (requires Node.js 18+):

npm install -g mcp-remote

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "wazuh": {
      "command": "mcp-remote",
      "args": [
        "http://YOUR_SERVER_IP:8000/sse",
        "--allow-http"
      ]
    }
  }
}

Fully quit Claude Desktop (tray icon → Quit) and relaunch. You should see the tools icon in the chat input.

Option B — stdio (local, same machine)

If Claude Desktop and the MCP server run on the same machine, use stdio transport:

{
  "mcpServers": {
    "wazuh": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "wazuh_mcp"],
      "env": {
        "WAZUH_HOST": "https://your-wazuh:55000",
        "WAZUH_USER": "wazuh-mcp",
        "WAZUH_PASS": "YourPassword",
        "WAZUH_INDEXER_HOST": "https://your-indexer:9200",
        "WAZUH_INDEXER_USER": "wazuh-readonly",
        "WAZUH_INDEXER_PASS": "YourPassword",
        "WAZUH_VERIFY_SSL": "false",
        "WAZUH_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

---

Environment Variables

Required

Transport

Security

Index Patterns

Optional Integrations

---

Tool Reference

Agents (6 tools)

Alerts (9 tools)

Vulnerabilities (4 tools)

Active Response (3 tools)

File Integrity Monitoring (4 tools)

Compliance (4 tools)

Fleet Inventory (7 tools)

SCA (4 tools)

CDB Lists (5 tools)

Rules & Decoders (6 tools)

Threat Intelligence (3 tools)

Threat Hunting (4 tools)

MITRE ATT&CK (2 tools)

Incidents (5 tools)

Reporting (3 tools)

Integrations (3 tools)

Notifications (3 tools)

Agent Onboarding (3 tools)

Cluster Health (2 tools)

Archive Search (2 tools)

Alert Suppression (3 tools)

---

MCP Prompts

Available as / commands in Claude Code and prompt-aware clients.

---

Architecture

┌─────────────────────────────┐        ┌──────────────────────────────────────┐
│      Claude Desktop         │        │       Wazuh Server / Docker Host     │
│                             │        │                                      │
│  ┌───────────────────────┐  │  HTTP  │  ┌────────────────────────────────┐  │
│  │    Claude Desktop     │◄─┼────────┼─►│   wazuh-mcp container          │  │
│  │  (mcp-remote bridge)  │  │  /sse  │  │   port 8000, HTTP/SSE          │  │
│  └───────────────────────┘  │        │  └────────────┬───────────────────┘  │
└─────────────────────────────┘        │               │                      │
                                       │     ┌─────────┴──────────┐          │
                                       │     │                    │          │
                                       │  :55000             :9200           │
                                       │  Wazuh Manager    Wazuh Indexer     │
                                       │  REST API         (OpenSearch)      │
                                       └────────────────────────────────────┘

Project Layout

wazuh-mcp/
├── wazuh_mcp/
│   ├── __main__.py          # entry point — transport selection
│   ├── server.py            # FastMCP app, shared helpers, MCP prompts
│   ├── config.py            # Config dataclass, env loading
│   ├── helpers.py           # trim_alert, time_window utilities
│   └── tools/               # 21 domain modules
│       ├── agents.py        # agent + group management
│       ├── alerts.py        # alert search + anomaly detection
│       ├── vulnerabilities.py
│       ├── active_response.py
│       ├── fim.py
│       ├── compliance.py
│       ├── fleet.py         # per-agent + fleet-wide inventory
│       ├── sca.py
│       ├── cdb.py
│       ├── rules.py
│       ├── threat_intel.py
│       ├── threat_hunting.py
│       ├── mitre.py
│       ├── incidents.py
│       ├── reporting.py
│       ├── integrations.py  # Jira, TheHive
│       ├── notifications.py # Slack, email
│       ├── onboarding.py
│       ├── cluster.py
│       ├── archive.py
│       └── suppression.py
├── compose.yaml
├── Dockerfile
├── env.example
├── pyproject.toml
└── requirements.txt

---

Optional Integrations

All integrations are opt-in. Tools degrade gracefully if credentials are absent.

Threat Intelligence

• VirusTotal — VIRUSTOTAL_API_KEY — free tier: 500 lookups/day at virustotal.com
• AbuseIPDB — ABUSEIPDB_API_KEY — free tier: 1000/day at abuseipdb.com

Ticketing

• Jira — JIRA_URL, JIRA_USER, JIRA_TOKEN, JIRA_PROJECT_KEY
• TheHive — THEHIVE_URL, THEHIVE_API_KEY

Notifications

• Slack webhook — SLACK_WEBHOOK_URL (simpler, single channel)
• Slack bot token — SLACK_BOT_TOKEN + SLACK_DEFAULT_CHANNEL (multi-channel)
• Email (SMTP) — SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM

---

Security Considerations

Dedicated read-only accounts. Create separate Wazuh Manager API and Indexer users with minimum permissions. Never use admin.

Write guard. WAZUH_ALLOW_WRITES=false (default) disables restart_agent, run_active_response, add_to_cdb_list, remove_from_cdb_list, tag_alert, expire_suppression, and bulk_suppress_rule. Enable only when explicitly delegating remediation.

Bind to trusted interfaces. For Docker on a private network, 0.0.0.0 with a firewall rule on port 8000 is acceptable. Never expose port 8000 to the internet.

TLS for production. WAZUH_VERIFY_SSL=false is lab-only. In production: valid CA chain, WAZUH_VERIFY_SSL=true, and an nginx/Caddy TLS reverse proxy in front of port 8000 (removes --allow-http requirement).

API keys stay in .env. The .env file is in .gitignore. Never commit VIRUSTOTAL_API_KEY, ABUSEIPDB_API_KEY, Jira/TheHive tokens, or SMTP credentials.

---

Common Issues

HTTP 421 Invalid Host header from mcp-remote

The MCP SDK’s DNS-rebinding protection blocks non-localhost Host headers. This is already disabled in server.py via TransportSecuritySettings(enable_dns_rebinding_protection=False). If you see this, ensure you are running the latest code.

ECONNREFUSED on port 8000

docker compose ps           # check container is Up
docker compose logs wazuh-mcp | tail -30

Ensure WAZUH_MCP_HOST=0.0.0.0 is set in .env, not 127.0.0.1.

Empty results from alert/vulnerability tools

curl -sk -u USER:PASS https://INDEXER:9200/_cat/indices?h=index | grep wazuh

Update WAZUH_ALERTS_INDEX and WAZUH_VULN_INDEX in .env to match your actual index names.

401 Unauthorized from Wazuh Manager API

curl -k -X POST -u "wazuh-mcp:password" https://MANAGER:55000/security/user/authenticate

If this returns a token, credentials are correct but RBAC is missing. Add read permissions for agents, rules, sca, syscollector, syscheck.

Archive tools return no results

Archive logging must be enabled in ossec.conf:

  
    yes
    yes
  

Restart Wazuh manager after changing this.

Claude Desktop shows no tools

1. Fully quit Claude Desktop (not just close the window).
2. Verify mcp-remote connects: mcp-remote http://SERVER:8000/sse --allow-http (should hang silently).
3. Check the config file uses command/args format, not the url shorthand.
4. Relaunch Claude Desktop and look for the tools icon in the chat input bar.

---

Sources

• Wazuh REST API Documentation
• Wazuh Indexer Documentation
• Model Context Protocol Specification
• FastMCP Python SDK
• mcp-remote