Skip to content
Back to search

Wazuh-MCP-Server

Production-grade MCP server for Wazuh SIEM — 55 security tools for alert triage, threat hunting, vulnerability management, compliance (PCI DSS, GDPR, HIPAA, NIST CSF, ISO 27001) and active response. Connect Claude or any LLM to your SOC. OAuth 2.1, RBAC, multi-cluster, air-gap ready.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/gensecaihq/Wazuh-MCP-Server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/gensecaihq/Wazuh-MCP-Server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gensecaihq--wazuh-mcp-server/badge.svg)](/listings/gensecaihq--wazuh-mcp-server)

HTML

<a href="/listings/gensecaihq--wazuh-mcp-server"><img src="/api/listings/gensecaihq--wazuh-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Docker with Compose v2 and a Wazuh Manager API user.

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

Set the Wazuh connection in `.env`:

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

# Needed for alert, vulnerability and alert-backed compliance tools
WAZUH_INDEXER_HOST=your-wazuh-indexer
WAZUH_INDEXER_USER=your-indexer-user
WAZUH_INDEXER_PASS=your-indexer-password

The Manager's TLS certificate is verified. A stock Wazuh install uses a self-signed API certificate that cannot pass verification, so either reissue it for your host and set `WAZUH_CA_BUNDLE`, or, for a first test, add `WAZUH_ALLOW_SELF_SIGNED=true` (connects without verification; logged at startup). Details: [Manager TLS](docs/configuration.md#manager-tls).

Generate the signing secret and an API key. `compose.yml` runs the server with `ENVIRONMENT=production`, which refuses to start without `AUTH_SECRET_KEY`:

echo "AUTH_SECRET_KEY=$(openssl rand -hex 32)" >> .env
echo "MCP_API_KEY=wazuh_$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')" >> .env

Start the server and check it:

docker compose up -d
curl http://localhost:3000/health     # liveness
curl http://localhost:3000/ready      # checks Manager/Indexer reachability

Exchange the API key for a bearer token (valid for `TOKEN_LIFETIME_HOURS`, default 24):

curl -s -X POST http://localhost:3000/auth/token -H 'Content-Type: application/json' \
  -d "{\"api_key\": \"$(grep ^MCP_API_KEY= .env | cut -d= -f2)\"}"

The key is read-only. To allow active-response tools, add `MCP_API_KEY_SCOPES="wazuh:read wazuh:write"` to `.env`, recreate the container with `docker compose up -d` (`restart` keeps the old environment), and mint a new token.

Compose publishes the port on `127.0.0.1` only. The server speaks plain HTTP; put a TLS-terminating reverse proxy in front before exposing it (set `MCP_BIND` to change the host bind address).

`python3 deploy.py` (or `deploy.bat` on Windows) performs the same steps, generating `AUTH_SECRET_KEY` and `MCP_API_KEY` if they are missing.

Pre-built image

Multi-arch images (amd64, arm64) are published to GitHub Container Registry and can be pulled without logging in:

docker pull ghcr.io/gensecaihq/wazuh-mcp-server:latest   # tracks main
docker pull ghcr.io/gensecaihq/wazuh-mcp-server:5.0.0    # latest tagged release

`latest` is built from `main` and may include changes listed under *Unreleased* in the [changelog](CHANGELOG.md). Release images are tagged `5.0.0`, `5.0` and `v5.0.0` (4.3.0 and earlier have no `v`-prefixed tag). Upgrading from 4.x: read [UPGRADING.md](UPGRADING.md) first.

docker run -d --name wazuh-mcp-server --env-file .env -e MCP_HOST=0.0.0.0 -e ENVIRONMENT=production \
  -p 127.0.0.1:3000:3000 ghcr.io/gensecaihq/wazuh-mcp-server:latest

`MCP_HOST=0.0.0.0` is required inside a container because `.env.example` sets `MCP_HOST=127.0.0.1` for bare-metal installs. `-e` wins over `--env-file`, so `ENVIRONMENT=production` holds even if your `.env` sets another value.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 390 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Wazuh MCP Server
  3. **A Model Context Protocol (MCP) server for the Wazuh SIEM.**
  4. Lets an MCP client — Claude, Open WebUI backed by a local model, or any client that speaks Streamable HTTP — query alerts, agents, vulnerabilities and compliance data, and dispatch active responses, with scope-based access control and audit logging.
  5. [![CI](https://github.com/gensecaihq/Wazuh-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/gensecaihq/Wazuh-MCP-Server/actions/workflows/ci.yml)
  6. [![Security Audit](https://github.com/gensecaihq/Wazuh-MCP-Server/actions/workflows/security.yml/badge.svg)](https://github.com/gensecaihq/Wazuh-MCP-Server/actions/workflows/security.yml)
  7. [![Release](https://img.shields.io/github/v/release/gensecaihq/Wazuh-MCP-Server?color=2ea44f&label=release)](https://github.com/gensecaihq/Wazuh-MCP-Server/releases/latest)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  9. [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
  10. [![MCP 2026-07-28](https://img.shields.io/badge/MCP-2026--07--28-6E56CF)](https://modelcontextprotocol.io/specification/2026-07-28)
  11. [![Wazuh 4.8.0–4.14.7](https://img.shields.io/badge/Wazuh-4.8.0–4.14.7-005792?logo=wazuh&logoColor=white)](WAZUH_COMPATIBILITY.md)
  12. [![GHCR image](https://img.shields.io/badge/ghcr.io-image-2496ED?logo=docker&logoColor=white)](https://github.com/gensecaihq/Wazuh-MCP-Server/pkgs/container/wazuh-mcp-server)
  13. [Quick Start](#quick-start) · [Clients](#connecting-clients) · [Tools](#tools) · [Security](#security-model) · [Configuration](#configuration) · [Docs](#documentation) · [Changelog](CHANGELOG.md) · [Upgrading](UPGRADING.md)
  14. </div>
  15. ---
  16. ## Overview
  17. - **55 tools** in 8 toolsets: alerts, agents, vulnerabilities, threat analysis, compliance (PCI-DSS, HIPAA, SOX, GDPR, NIST, ISO 27001:2022), manager/cluster health, and active response with verification and rollback. Also 5 guided prompts, 6 resources and 3 resource templates.
  18. - **Read-only by default.** The 14 state-changing tools require the `wazuh:write` scope, which is never granted implicitly.
  19. - **MCP transport:** Streamable HTTP at `/mcp`. Serves protocol revision 2026-07-28 (stateless requests) and the `initialize` handshake for 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. The legacy HTTP+SSE endpoint `/sse` returns `410 Gone`.
  20. - **Authentication:** bearer tokens minted from an API key; OAuth 2.0 (authorization code + PKCE) with sign-in by API key or at an OpenID Connect provider (Entra ID, Google Workspace, Okta, Keycloak); or no auth for local development.
  21. - **Deployment:** Docker Compose or a published multi-arch image; optional Redis for multi-instance sessions; optional multi-cluster routing.
  22. - **Local models:** a vLLM + Open WebUI stack (`compose.local-llm.yml`) and toolset filtering for small models. The only tool that calls a service outside your Wazuh deployment is the optional `search_external_context` (You.com), which can be disabled on its own.
  23. Supported Wazuh versions: 4.8.0 through 4.14.7. Alert, vulnerability and alert-backed compliance tools need the Wazuh Indexer. See [WAZUH_COMPATIBILITY.md](WAZUH_COMPATIBILITY.md).
  24. ---
  25. ## Quick Start
  26. Requires Docker with Compose v2 and a Wazuh Manager API user.
  27. ```bash
  28. git clone https://github.com/gensecaihq/Wazuh-MCP-Server.git
  29. cd Wazuh-MCP-Server
  30. cp .env.example .env
  31. ```
  32. Set the Wazuh connection in `.env`:
  33. ```env
  34. WAZUH_HOST=your-wazuh-manager
  35. WAZUH_USER=your-api-user
  36. WAZUH_PASS=your-api-password
  37. # Needed for alert, vulnerability and alert-backed compliance tools
  38. WAZUH_INDEXER_HOST=your-wazuh-indexer
  39. WAZUH_INDEXER_USER=your-indexer-user
  40. WAZUH_INDEXER_PASS=your-indexer-password
  41. ```
  42. The Manager's TLS certificate is verified. A stock Wazuh install uses a self-signed API certificate that cannot pass verification, so either reissue it for your host and set `WAZUH_CA_BUNDLE`, or, for a first test, add `WAZUH_ALLOW_SELF_SIGNED=true` (connects without verification; logged at startup). Details: [Manager TLS](docs/configuration.md#manager-tls).
  43. Generate the signing secret and an API key. `compose.yml` runs the server with `ENVIRONMENT=production`, which refuses to start without `AUTH_SECRET_KEY`:
  44. ```bash
  45. echo "AUTH_SECRET_KEY=$(openssl rand -hex 32)" >> .env
  46. echo "MCP_API_KEY=wazuh_$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')" >> .env
  47. ```
  48. Start the server and check it:
  49. ```bash
  50. docker compose up -d
  51. curl http://localhost:3000/health # liveness
  52. curl http://localhost:3000/ready # checks Manager/Indexer reachability
  53. ```
  54. Exchange the API key for a bearer token (valid for `TOKEN_LIFETIME_HOURS`, default 24):
  55. ```bash
  56. curl -s -X POST http://localhost:3000/auth/token -H 'Content-Type: application/json' \
  57. -d "{\"api_key\": \"$(grep ^MCP_API_KEY= .env | cut -d= -f2)\"}"
  58. ```
  59. The key is read-only. To allow active-response tools, add `MCP_API_KEY_SCOPES="wazuh:read wazuh:write"` to `.env`, recreate the container with `docker compose up -d` (`restart` keeps the old environment), and mint a new token.
  60. Compose publishes the port on `127.0.0.1` only. The server speaks plain HTTP; put a TLS-terminating reverse proxy in front before exposing it (set `MCP_BIND` to change the host bind address).
  61. `python3 deploy.py` (or `deploy.bat` on Windows) performs the same steps, generating `AUTH_SECRET_KEY` and `MCP_API_KEY` if they are missing.
  62. ### Pre-built image
  63. Multi-arch images (amd64, arm64) are published to GitHub Container Registry and can be pulled without logging in:
  64. ```bash
  65. docker pull ghcr.io/gensecaihq/wazuh-mcp-server:latest # tracks main
  66. docker pull ghcr.io/gensecaihq/wazuh-mcp-server:5.0.0 # latest tagged release
  67. ```
  68. `latest` is built from `main` and may include changes listed under *Unreleased* in the [changelog](CHANGELOG.md). Release images are tagged `5.0.0`, `5.0` and `v5.0.0` (4.3.0 and earlier have no `v`-prefixed tag). Upgrading from 4.x: read [UPGRADING.md](UPGRADING.md) first.
  69. ```bash
  70. docker run -d --name wazuh-mcp-server --env-file .env -e MCP_HOST=0.0.0.0 -e ENVIRONMENT=production \
  71. -p 127.0.0.1:3000:3000 ghcr.io/gensecaihq/wazuh-mcp-server:latest
  72. ```
  73. `MCP_HOST=0.0.0.0` is required inside a container because `.env.example` sets `MCP_HOST=127.0.0.1` for bare-metal installs. `-e` wins over `--env-file`, so `ENVIRONMENT=production` holds even if your `.env` sets another value.
  74. ---
  75. ## Connecting Clients
  76. All clients use the Streamable HTTP endpoint `https://<your-host>/mcp`.
  77. | Client | Auth mode | How it authenticates |
  78. |--------|-----------|----------------------|
  79. | Claude custom connectors (claude.ai, Claude Desktop) | `oauth` | OAuth authorization code with PKCE. The server pre-registers a public client, `claude-desktop`, for Claude's callback URLs. Users sign in on the server's `/oauth/authorize` page with a `wazuh_` API key (the grant is capped at that key's scopes), or at your OpenID Connect provider when `OAUTH_IDP_ISSUER` is set. |
  80. | Open WebUI, LibreChat, scripts and other MCP clients | `bearer` (default) | `Authorization: Bearer <token>` using a token from `POST /auth/token`. |
  81. In OAuth mode, set `OAUTH_ISSUER_URL` to the server's public HTTPS URL (otherwise it is derived from each request, which behind a proxy may not be the public URL). Dynamic Client Registration (`/oauth/register`) is off unless `OAUTH_ENABLE_DCR=true`, and cannot be combined with `OAUTH_IDP_ISSUER`.
  82. Guides: [Claude Integration](docs/CLAUDE_INTEGRATION.md) · [Local LLMs](docs/LOCAL_LLM.md)
  83. ---
  84. ## Local LLMs
  85. The server does not call a model; it only executes tools. To keep SIEM data on-premises, pair it with a local model:
  86. ```bash
  87. cat >> .env <<EOF
  88. VLLM_API_KEY=$(openssl rand -hex 32)
  89. WEBUI_SECRET_KEY=$(openssl rand -hex 32)
  90. EOF
  91. docker compose -f compose.yml -f compose.local-llm.yml up -d
  92. ```
  93. This adds vLLM (default model Qwen3.6-35B-A3B FP8, about 42 GB of VRAM on one NVIDIA GPU; not published on a host port) and Open WebUI on `127.0.0.1:8080`. In Open WebUI's admin settings, add an MCP (Streamable HTTP) tool server at `http://wazuh-main-server:3000/mcp` with a bearer token.
  94. For smaller models, expose fewer tools with `WAZUH_TOOLSETS` / `WAZUH_DISABLED_TOOLS`, and check tool selection before rollout with `evals/tool_selection.py` (25 SOC scenarios, including two prompt-injection cases, against any OpenAI-compatible endpoint; no tools are executed). Model sizing, Ollama and LiteLLM are covered in the [Local LLM Guide](docs/LOCAL_LLM.md).
  95. ---
  96. ## Tools
  97. 55 tools, grouped into toolsets that can be enabled with `WAZUH_TOOLSETS` (comma-separated; default all). **R** = `wazuh:read`, **W** = `wazuh:write`.
  98. | Toolset | Count | Tools |
  99. |---------|-------|-------|
  100. | `alerts` | 5 R | `get_wazuh_alerts`, `get_wazuh_alert_summary`, `get_alerts_aggregated`, `analyze_alert_patterns`, `search_security_events` |
  101. | `agents` | 6 R | `get_wazuh_agents`, `get_wazuh_running_agents`, `check_agent_health`, `get_agent_processes`, `get_agent_ports`, `get_agent_configuration` |
  102. | `vulnerabilities` | 3 R | `get_wazuh_vulnerabilities`, `get_wazuh_critical_vulnerabilities`, `get_wazuh_vulnerability_summary` |
  103. | `analysis` | 5 R | `analyze_security_threat`, `check_ioc_reputation`, `perform_risk_assessment`, `get_top_security_threats`, `generate_security_report` |
  104. | `web_search` | 1 R | `search_external_context` — You.com web search; returns a "not enabled" result unless `YDC_API_KEY` is set |
  105. | `compliance` | 6 R | `run_compliance_check` (PCI-DSS, HIPAA, SOX, GDPR, NIST, ISO27001), `get_iso27001_dashboard`, `get_iso27001_control_detail`, `get_iso27001_gap_analysis`, `get_iso27001_alerts`, `get_sca_policy_checks` |
  106. | `system` | 10 R | `get_wazuh_statistics`, `get_wazuh_weekly_stats`, `get_wazuh_cluster_health`, `get_wazuh_cluster_nodes`, `get_wazuh_rules_summary`, `get_wazuh_remoted_stats`, `get_wazuh_log_collector_stats`, `search_wazuh_manager_logs`, `get_wazuh_manager_error_logs`, `validate_wazuh_connection` |
  107. | `response` — containment | 9 W | `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` |
  108. | `response` — rollback | 5 W | `wazuh_unisolate_host`, `wazuh_enable_user`, `wazuh_restore_file`, `wazuh_firewall_allow`, `wazuh_host_allow` |
  109. | `response` — verification | 5 R | `wazuh_check_blocked_ip`, `wazuh_check_agent_isolation`, `wazuh_check_process`, `wazuh_check_user_status`, `wazuh_check_file_quarantine` |
  110. - Totals: 41 read tools, 14 write tools. Tokens without `wazuh:write` do not see the write tools in `tools/list`.
  111. - In multi-cluster mode a 56th tool, `list_wazuh_clusters` (`system`, read), is added and every tool accepts an optional `cluster_id`.
  112. - `WAZUH_DISABLED_TOOLS` hides individual tools. Hidden tools are removed from `tools/list` and refused by `tools/call`; unknown toolset or tool names stop the server at startup.
  113. - Every tool carries MCP annotations derived from its scope: read tools are `readOnlyHint: true`; containment tools are `destructiveHint: true`; rollback tools are `destructiveHint: false`; only `search_external_context` is `openWorldHint: true`.
  114. - Input schemas are closed (`additionalProperties: false`); undeclared arguments are refused.
  115. - Timestamp filters accept ISO 8601 or OpenSearch date math (`now-24h`).
  116. - Prompts: `security_investigation`, `threat_hunt`, `compliance_audit`, `vulnerability_assessment`, `iso27001_assessment`.
  117. Per-tool parameters: [API documentation](docs/api/).
  118. ### Active response behaviour
  119. - Results report `execution_status: "dispatched"`: Wazuh confirms the command was delivered to the agent, not that it ran. Confirm the effect with the matching `wazuh_check_*` tool.
  120. - Blocks are permanent until removed. Wazuh ignores the timeout for API-triggered commands, so a positive `duration` is refused.
  121. - `wazuh_firewall_allow` and `wazuh_host_allow` require an operator-deployed undo command (`WAZUH_AR_FIREWALL_UNDO_COMMAND`, `WAZUH_AR_HOSTDENY_UNDO_COMMAND`); without one they refuse.
  122. ---
  123. ## Security Model
  124. | Control | Behaviour |
  125. |---------|-----------|
  126. | **Scopes (RBAC)** | Each tool requires `wazuh:read` or `wazuh:write`. A token without a scope claim is read-only. `MCP_API_KEY` is read-only unless `MCP_API_KEY_SCOPES` includes `wazuh:write`. With `AUTH_MODE=none`, write tools are disabled unless `AUTHLESS_ALLOW_WRITE=true`. |
  127. | **Bearer tokens** | JWTs signed with `AUTH_SECRET_KEY`, must carry `exp`, and are bound to the API key they were minted from: revoking or rotating the key invalidates its tokens. Refresh tokens are not accepted as access tokens. |
  128. | **OAuth** | Authorization code flow with mandatory S256 PKCE, single-use codes, refresh-token rotation with replay detection, and revocation. Users sign in with a `wazuh_` API key (the grant is capped at that key's scopes, and its tokens end when the key is revoked) or at an OpenID Connect provider (ID token signature, issuer, audience, expiry and nonce verified; tenant, domain and user allow-lists; group-to-scope mapping), so scopes, rate limits and audit entries are per user. |
  129. | **Action guardrails** | IP-blocking tools refuse loopback, the Manager's address (when `WAZUH_HOST` is an IP) and anything in `WAZUH_PROTECTED_IPS`; the generic active-response tool does not dispatch IP blocks, quarantine, process kills or account disables. Actions and restarts aimed at agent `000` (the Manager) need `WAZUH_ALLOW_MANAGER_AR=true`; fleet-wide blocks need `WAZUH_ALLOW_FLEET_AR=true`; quarantine refuses system and agent directories. In production, write tools require `confirm=true` (`WAZUH_REQUIRE_ACTION_CONFIRMATION`). |
  130. | **Wazuh TLS** | The Manager and Indexer certificates are verified by default, against the system store or `WAZUH_CA_BUNDLE`. Disabling Manager verification (`WAZUH_ALLOW_SELF_SIGNED=true`) is logged at startup, as an error in production. |
  131. | **Audit log** | Every write-tool call that passes the scope and confirmation checks is logged before and after execution (logger `wazuh_mcp_server.audit`) with the principal, session, arguments and outcome. |
  132. | **Redaction** | Credentials and tokens are redacted from tool output in every response format, and from server logs. |
  133. | **Input validation** | Typed validation of agent IDs, IPs, paths and command names; Indexer queries are built as Query DSL, not by string interpolation. |
  134. | **Rate limiting** | Sliding window, default 100 requests per 60 s (`RATE_LIMIT_REQUESTS`, `RATE_LIMIT_WINDOW`): per principal and client IP on `/mcp` and `/`, per client IP on other endpoints except the probe endpoints (`/health`, `/ready`, `/metrics` and their `/healthz`, `/readyz`, `/live`, `/livez` aliases). Failed authentication is rate limited by client IP. Set `TRUSTED_PROXIES` when running behind a proxy. |
  135. | **Resource bounds** | Circuit breaker on Wazuh calls: opens after 5 consecutive failures, retries after 60 s. Oversized tool results are truncated with a note (`MAX_TOOL_RESPONSE_CHARS`). `limit` on `get_wazuh_alerts` and `search_security_events` is capped at `MAX_ALERTS_PER_QUERY` (default 1000). The in-memory session store is capped at `MAX_SESSIONS` (1000) and `MAX_SESSIONS_PER_PRINCIPAL` (100), and stored client metadata is truncated. |
  136. | **Container** | Runs as UID 1000; `compose.yml` sets a read-only root filesystem, `cap_drop: ALL` and `no-new-privileges`. The runtime image does not include pip. |
  137. There is no built-in TLS listener; terminate TLS at a reverse proxy or load balancer. Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
  138. ---
  139. ## Configuration
  140. All settings are environment variables (usually via `.env`). The ones most deployments touch:
  141. | Variable | Default | Purpose |
  142. |----------|---------|---------|
  143. | `WAZUH_HOST`, `WAZUH_USER`, `WAZUH_PASS` | — | Manager API connection (required) |
  144. | `WAZUH_PORT` | `55000` | Manager API port |
  145. | `WAZUH_CA_BUNDLE` | — | CA PEM used instead of the system store to verify the Manager and Indexer; see [Manager TLS](docs/configuration.md#manager-tls) |
  146. | `WAZUH_ALLOW_SELF_SIGNED` | `false` | `true` connects to the Manager without certificate verification (logged at startup) |
  147. | `WAZUH_INDEXER_HOST`, `WAZUH_INDEXER_USER`, `WAZUH_INDEXER_PASS` | — | Indexer connection; an `http://` host prefix selects plain HTTP |
  148. | `WAZUH_INDEXER_PORT` | `9200` | Indexer port |
  149. | `ENVIRONMENT` | `development` | `production` requires a strong `AUTH_SECRET_KEY` (unless `AUTH_MODE=none`) |
  150. | `AUTH_MODE` | `bearer` | `bearer`, `oauth` or `none` |
  151. | `AUTH_SECRET_KEY` | generated per process outside production | Token signing key; use the same value on every instance |
  152. | `MCP_API_KEY` / `API_KEYS` | generated per process if unset (printed only in development) | A single `wazuh_` key, or a JSON list of hashed keys with per-key scopes |
  153. | `MCP_API_KEY_SCOPES` | `wazuh:read` | Space-separated scopes for `MCP_API_KEY` |
  154. | `OAUTH_ISSUER_URL` | derived from the request | Public HTTPS URL of the server, for `AUTH_MODE=oauth` |
  155. | `OAUTH_IDP_ISSUER` | — | OpenID Connect provider for OAuth sign-in (with `OAUTH_IDP_CLIENT_ID`); API-key sign-in when unset |
  156. | `WAZUH_REQUIRE_ACTION_CONFIRMATION` | `true` in production, else `false` | Write tools require `confirm=true` |
  157. | `MCP_HOST`, `MCP_PORT` | `127.0.0.1` (`0.0.0.0` in the Docker image), `3000` | Bind address and port |
  158. | `ALLOWED_ORIGINS` | `https://claude.ai,http://localhost:3000` | CORS allow-list (exact match) |
  159. | `WAZUH_TOOLSETS`, `WAZUH_DISABLED_TOOLS` | all enabled | Limit the exposed tools |
  160. | `REDIS_URL` | — | Shared session store for multi-instance deployments |
  161. | `WAZUH_CLUSTERS_FILE` | `./config/clusters.json` | Multi-cluster topology; single-cluster mode when absent |
  162. | `RESPONSE_FORMAT` | `json` | `gcf` encodes alert, event and vulnerability collections in the compact GCF format (lossless; falls back to JSON if the encoder is unavailable) |
  163. | `YDC_API_KEY` | — | Enables `search_external_context` |
  164. Complete reference, including OAuth TTLs, rate limits, sessions and active-response settings: [Configuration Guide](docs/configuration.md). Multi-cluster setup: [Multi-Cluster Guide](docs/MULTI_CLUSTER.md) and [`config/clusters.json.example`](config/clusters.json.example).
  165. ### Running from source
  166. ```bash
  167. python -m venv .venv && source .venv/bin/activate
  168. pip install -e ".[redis,gcf]" # extras are optional
  169. set -a; . ./.env; set +a # the server reads the environment, not .env
  170. python -m wazuh_mcp_server
  171. ```
  172. Requires Python 3.11 or later.
  173. ---
  174. ## HTTP Endpoints
  175. | Endpoint | Method | Description |
  176. |----------|--------|-------------|
  177. | `/mcp` | POST, GET, DELETE | MCP Streamable HTTP |
  178. | `/` | POST, GET | Same handler as `/mcp` |
  179. | `/sse` | GET, POST | Returns `410 Gone`; use `/mcp` |
  180. | `/health` | GET | Liveness; no dependency checks |
  181. | `/ready` | GET | Readiness; 503 when the Manager, Indexer or memory headroom check fails |
  182. | `/metrics` | GET | Prometheus metrics |
  183. | `/auth/token` | POST | Exchange an API key for a bearer JWT |
  184. | `/.well-known/oauth-authorization-server` | GET | OAuth metadata (RFC 8414), `AUTH_MODE=oauth` only |
  185. | `/.well-known/oauth-protected-resource` | GET | Protected-resource metadata (RFC 9728), `AUTH_MODE=oauth` only |
  186. | `/oauth/authorize`, `/oauth/token`, `/oauth/revoke`, `/oauth/register`, `/oauth/callback` | GET/POST | OAuth endpoints, `AUTH_MODE=oauth` only (`/oauth/register` requires `OAUTH_ENABLE_DCR=true` and no `OAUTH_IDP_ISSUER`; `/oauth/callback` is the OpenID Connect redirect URI and needs `OAUTH_IDP_ISSUER`) |
  187. | `/docs`, `/redoc`, `/openapi.json` | GET | OpenAPI documentation |
  188. ---
  189. ## Project Layout
  190. ```
  191. src/wazuh_mcp_server/
  192. ├── server.py # FastAPI app, MCP protocol handling, CORS/Origin checks, tool definitions and dispatch
  193. ├── toolsets.py # Toolset membership, WAZUH_TOOLSETS resolution, tool annotations
  194. ├── auth.py # API keys and bearer JWTs
  195. ├── oauth.py # OAuth 2.0 authorization server (PKCE, API-key sign-in)
  196. ├── oidc.py # OpenID Connect sign-in at an external identity provider
  197. ├── config.py # Environment configuration and startup validation
  198. ├── security.py # Rate limiting, request and input validation, log redaction
  199. ├── clusters.py # Multi-cluster registry and Cross-Cluster Search routing
  200. ├── session_store.py # In-memory and Redis session storage
  201. ├── resilience.py # Circuit breakers, retries, graceful shutdown
  202. ├── monitoring.py # Prometheus metrics, structured logging
  203. ├── gcf_format.py # Optional GCF response encoding
  204. └── api/
  205. ├── wazuh_client.py # Wazuh Manager REST API client
  206. └── wazuh_indexer.py # Wazuh Indexer (OpenSearch) client
  207. ```
  208. ---
  209. ## Documentation
  210. | Document | Contents |
  211. |----------|----------|
  212. | [Configuration Guide](docs/configuration.md) | Every environment variable, auth modes, RBAC |
  213. | [Claude Integration](docs/CLAUDE_INTEGRATION.md) | Connecting Claude custom connectors |
  214. | [Local LLM Guide](docs/LOCAL_LLM.md) | vLLM, Open WebUI, Ollama, LiteLLM, tool-selection eval |
  215. | [Multi-Cluster](docs/MULTI_CLUSTER.md) | Named clusters and Cross-Cluster Search |
  216. | [Operations](docs/OPERATIONS.md) | Deployment, monitoring, maintenance |
  217. | [Advanced Features](docs/ADVANCED_FEATURES.md) | Multi-instance deployment, compact output |
  218. | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and fixes |
  219. | [API Reference](docs/api/) | Per-tool parameters |
  220. | [Security Hardening](docs/security/) | Hardening guidance |
  221. | [MCP Compliance](MCP_COMPLIANCE_VERIFICATION.md) | Protocol conformance notes |
  222. | [Wazuh Compatibility](WAZUH_COMPATIBILITY.md) | Supported Wazuh versions |
  223. | [Upgrading](UPGRADING.md) · [Changelog](CHANGELOG.md) · [Security Policy](SECURITY.md) | Release notes and policies |
  224. Related project: [Wazuh Autopilot](https://github.com/gensecaihq/Wazuh-Autopilot) builds automated SOC workflows on top of this server.
  225. ---
  226. ## Contributing
  227. See [CONTRIBUTING.md](CONTRIBUTING.md). Bugs, feature requests and questions go to [Issues](https://github.com/gensecaihq/Wazuh-MCP-Server/issues), and security reports to a private [security advisory](https://github.com/gensecaihq/Wazuh-MCP-Server/security/advisories/new).
  228. ---
  229. ## License
  230. [MIT](LICENSE)
  231. ---
  232. ## Acknowledgments
  233. Thanks to everyone who has contributed code, reviews, bug reports and design feedback. See also [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).
  234. **Code and pull requests**
  235. - <img src="https://github.com/andrzej-piotrowski-pl.png?size=48" width="24" height="24" alt=""> [@andrzej-piotrowski-pl](https://github.com/andrzej-piotrowski-pl) — ISO 27001:2022 compliance tools: Annex A control mapping, domain scoring, gap analysis (#74)
  236. - <img src="https://github.com/blackwell-systems.png?size=48" width="24" height="24" alt=""> [@blackwell-systems](https://github.com/blackwell-systems) — opt-in GCF response encoding for record tools (#102, #104)
  237. - <img src="https://github.com/lucascruzb.png?size=48" width="24" height="24" alt=""> [@lucascruzb](https://github.com/lucascruzb) — period-wide alert aggregation via scroll, the basis of `get_alerts_aggregated` (#79)
  238. - <img src="https://github.com/kanylbullen.png?size=48" width="24" height="24" alt=""> [@kanylbullen](https://github.com/kanylbullen) — compact output mode for token-efficient responses (#65)
  239. - <img src="https://github.com/mouse-value-add.png?size=48" width="24" height="24" alt=""> [@mouse-value-add](https://github.com/mouse-value-add) — optional You.com web-search context (#85)
  240. - <img src="https://github.com/DrRSatzteil.png?size=48" width="24" height="24" alt=""> [@DrRSatzteil](https://github.com/DrRSatzteil) — `tools/list` pagination fix (#70)
  241. - <img src="https://github.com/SiM22.png?size=48" width="24" height="24" alt=""> [@SiM22](https://github.com/SiM22) — MCP 2025-06-18 support for Windsurf compatibility (#66)
  242. - <img src="https://github.com/aiunmukto.png?size=48" width="24" height="24" alt=""> [@aiunmukto](https://github.com/aiunmukto) — `.env.example` (#12), an early CI workflow and the Glama registry listing
  243. - <img src="https://github.com/Karibusan.png?size=48" width="24" height="24" alt=""> [@Karibusan](https://github.com/Karibusan) — dependency fixes (#38)
  244. - <img src="https://github.com/lwsinclair.png?size=48" width="24" height="24" alt=""> [@lwsinclair](https://github.com/lwsinclair) — MseeP.ai listing (#9)
  245. - <img src="https://github.com/markeclaudio.png?size=48" width="24" height="24" alt=""> [@markeclaudio](https://github.com/markeclaudio) — OpenID Connect sign-in (#123), active-response guard-rails (#124, #125), session-store bounds (#126), Manager TLS verification by default (#127)
  246. - <img src="https://github.com/MilkyWay88.png?size=48" width="24" height="24" alt=""> [@MilkyWay88](https://github.com/MilkyWay88) and <img src="https://github.com/taylorwalton.png?size=48" width="24" height="24" alt=""> [@taylorwalton](https://github.com/taylorwalton) — early pull requests on configuration, logging and packaging
  247. **Bug reports and discussions**
  248. <img src="https://github.com/cbassonbgroup.png?size=48" width="24" height="24" alt=""> [@cbassonbgroup](https://github.com/cbassonbgroup), <img src="https://github.com/cybersentinel-06.png?size=48" width="24" height="24" alt=""> [@cybersentinel-06](https://github.com/cybersentinel-06), <img src="https://github.com/daod-arshad.png?size=48" width="24" height="24" alt=""> [@daod-arshad](https://github.com/daod-arshad), <img src="https://github.com/mamema.png?size=48" width="24" height="24" alt=""> [@mamema](https://github.com/mamema), <img src="https://github.com/marcolinux46.png?size=48" width="24" height="24" alt=""> [@marcolinux46](https://github.com/marcolinux46), <img src="https://github.com/matveevandrey.png?size=48" width="24" height="24" alt=""> [@matveevandrey](https://github.com/matveevandrey), <img src="https://github.com/punkpeye.png?size=48" width="24" height="24" alt=""> [@punkpeye](https://github.com/punkpeye), <img src="https://github.com/tonyliu9189.png?size=48" width="24" height="24" alt=""> [@tonyliu9189](https://github.com/tonyliu9189), <img src="https://github.com/Uberkarhu.png?size=48" width="24" height="24" alt=""> [@Uberkarhu](https://github.com/Uberkarhu), <img src="https://github.com/bl4ck5w4n07.png?size=48" width="24" height="24" alt=""> [@bl4ck5w4n07](https://github.com/bl4ck5w4n07), <img src="https://github.com/gnix45.png?size=48" width="24" height="24" alt=""> [@gnix45](https://github.com/gnix45), <img src="https://github.com/hackdefendr.png?size=48" width="24" height="24" alt=""> [@hackdefendr](https://github.com/hackdefendr), <img src="https://github.com/melmasry1987.png?size=48" width="24" height="24" alt=""> [@melmasry1987](https://github.com/melmasry1987), <img src="https://github.com/Vasanth120v.png?size=48" width="24" height="24" alt=""> [@Vasanth120v](https://github.com/Vasanth120v), <img src="https://github.com/wqfh.png?size=48" width="24" height="24" alt=""> [@wqfh](https://github.com/wqfh)
  249. **Built on and works with**
  250. - [Wazuh](https://wazuh.com/) — open source security platform
  251. - [Model Context Protocol](https://modelcontextprotocol.io/) — the protocol this server implements
  252. - [vLLM](https://github.com/vllm-project/vllm), [Ollama](https://ollama.com/) and [Open WebUI](https://github.com/open-webui/open-webui) — local model serving and chat, used in the local LLM stack
  253. ---
  254. <details>
  255. <summary><strong>Contributors</strong></summary>
  256. <!-- CONTRIBUTORS-START -->
  257. ### Contributors
  258. | Avatar | Username | Contributions |
  259. |--------|----------|---------------|
  260. | <img src="https://github.com/alokemajumder.png" width="40" height="40" style="border-radius: 50%"/> | [@alokemajumder](https://github.com/alokemajumder) | 💻 Code, 🐛 Issues, 🔀 PRs, 💬 Discussions |
  261. | <img src="https://github.com/Karibusan.png" width="40" height="40" style="border-radius: 50%"/> | [@Karibusan](https://github.com/Karibusan) | 💻 Code, 🐛 Issues, 🔀 PRs |
  262. | <img src="https://github.com/gensecai-dev.png" width="40" height="40" style="border-radius: 50%"/> | [@gensecai-dev](https://github.com/gensecai-dev) | 💻 Code, 🔀 PRs, 💬 Discussions |
  263. | <img src="https://github.com/aiunmukto.png" width="40" height="40" style="border-radius: 50%"/> | [@aiunmukto](https://github.com/aiunmukto) | 💻 Code, 🔀 PRs |
  264. | <img src="https://github.com/andrzej-piotrowski-pl.png" width="40" height="40" style="border-radius: 50%"/> | [@andrzej-piotrowski-pl](https://github.com/andrzej-piotrowski-pl) | 💻 Code, 🔀 PRs |
  265. | <img src="https://github.com/blackwell-systems.png" width="40" height="40" style="border-radius: 50%"/> | [@blackwell-systems](https://github.com/blackwell-systems) | 💻 Code, 🔀 PRs |
  266. | <img src="https://github.com/kanylbullen.png" width="40" height="40" style="border-radius: 50%"/> | [@kanylbullen](https://github.com/kanylbullen) | 💻 Code, 🔀 PRs |
  267. | <img src="https://github.com/lucascruzb.png" width="40" height="40" style="border-radius: 50%"/> | [@lucascruzb](https://github.com/lucascruzb) | 💻 Code, 🔀 PRs |
  268. | <img src="https://github.com/lwsinclair.png" width="40" height="40" style="border-radius: 50%"/> | [@lwsinclair](https://github.com/lwsinclair) | 💻 Code, 🔀 PRs |
  269. | <img src="https://github.com/mouse-value-add.png" width="40" height="40" style="border-radius: 50%"/> | [@mouse-value-add](https://github.com/mouse-value-add) | 💻 Code, 🔀 PRs |
  270. | <img src="https://github.com/SiM22.png" width="40" height="40" style="border-radius: 50%"/> | [@SiM22](https://github.com/SiM22) | 💻 Code, 🔀 PRs |
  271. | <img src="https://github.com/DrRSatzteil.png" width="40" height="40" style="border-radius: 50%"/> | [@DrRSatzteil](https://github.com/DrRSatzteil) | 🔀 PRs |
  272. | <img src="https://github.com/MilkyWay88.png" width="40" height="40" style="border-radius: 50%"/> | [@MilkyWay88](https://github.com/MilkyWay88) | 🔀 PRs |
  273. | <img src="https://github.com/taylorwalton.png" width="40" height="40" style="border-radius: 50%"/> | [@taylorwalton](https://github.com/taylorwalton) | 🔀 PRs |
  274. | <img src="https://github.com/cbassonbgroup.png" width="40" height="40" style="border-radius: 50%"/> | [@cbassonbgroup](https://github.com/cbassonbgroup) | 🐛 Issues |
  275. | <img src="https://github.com/cybersentinel-06.png" width="40" height="40" style="border-radius: 50%"/> | [@cybersentinel-06](https://github.com/cybersentinel-06) | 🐛 Issues |
  276. | <img src="https://github.com/daod-arshad.png" width="40" height="40" style="border-radius: 50%"/> | [@daod-arshad](https://github.com/daod-arshad) | 🐛 Issues |
  277. | <img src="https://github.com/mamema.png" width="40" height="40" style="border-radius: 50%"/> | [@mamema](https://github.com/mamema) | 🐛 Issues |
  278. | <img src="https://github.com/marcolinux46.png" width="40" height="40" style="border-radius: 50%"/> | [@marcolinux46](https://github.com/marcolinux46) | 🐛 Issues |
  279. | <img src="https://github.com/matveevandrey.png" width="40" height="40" style="border-radius: 50%"/> | [@matveevandrey](https://github.com/matveevandrey) | 🐛 Issues |
  280. | <img src="https://github.com/punkpeye.png" width="40" height="40" style="border-radius: 50%"/> | [@punkpeye](https://github.com/punkpeye) | 🐛 Issues |
  281. | <img src="https://github.com/tonyliu9189.png" width="40" height="40" style="border-radius: 50%"/> | [@tonyliu9189](https://github.com/tonyliu9189) | 🐛 Issues |
  282. | <img src="https://github.com/Uberkarhu.png" width="40" height="40" style="border-radius: 50%"/> | [@Uberkarhu](https://github.com/Uberkarhu) | 🐛 Issues |
  283. | <img src="https://github.com/bl4ck5w4n07.png" width="40" height="40" style="border-radius: 50%"/> | [@bl4ck5w4n07](https://github.com/bl4ck5w4n07) | 💬 Discussions |
  284. | <img src="https://github.com/gnix45.png" width="40" height="40" style="border-radius: 50%"/> | [@gnix45](https://github.com/gnix45) | 💬 Discussions |
  285. | <img src="https://github.com/hackdefendr.png" width="40" height="40" style="border-radius: 50%"/> | [@hackdefendr](https://github.com/hackdefendr) | 💬 Discussions |
  286. | <img src="https://github.com/melmasry1987.png" width="40" height="40" style="border-radius: 50%"/> | [@melmasry1987](https://github.com/melmasry1987) | 💬 Discussions |
  287. | <img src="https://github.com/Vasanth120v.png" width="40" height="40" style="border-radius: 50%"/> | [@Vasanth120v](https://github.com/Vasanth120v) | 💬 Discussions |
  288. | <img src="https://github.com/wqfh.png" width="40" height="40" style="border-radius: 50%"/> | [@wqfh](https://github.com/wqfh) | 💬 Discussions |
  289. **Legend:** 💻 Code · 🐛 Issues · 🔀 Pull Requests · 💬 Discussions
  290. <!-- CONTRIBUTORS-END -->
  291. > Auto-updated by [GitHub Actions](.github/workflows/update-contributors.yml)
  292. </details>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.