wazuh-mcp
Provides tools for querying the OpenSearch-backed Wazuh Indexer, including alert search, alert statistics, timelines, vulnerability state, index listing, and raw OpenSearch DSL queries restricted to wazuh-* indices.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wazuh-mcp Show me the top security alerts from the last 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
wazuh-mcp
An MCP server for querying a remote Wazuh deployment. It talks to both halves of Wazuh — the Manager API (agents, rules, inventory, configuration) and the Wazuh Indexer (alerts, vulnerability state) — and exposes 34 tools plus a composite report generator.
Read-only by default. State-changing tools exist but stay disabled unless you explicitly opt in.
Why both backends
Wazuh splits its data in a way that trips people up: the Manager API knows about agents, rules and inventory, but historical alerts are not there — they live in the Indexer (OpenSearch). Anything resembling "what fired last night" or "top threats this week" needs the Indexer. Configure both.
The 4.8 release also moved vulnerability detection results from the Manager API into the Indexer. This server detects the manager version and routes vulnerability queries to whichever backend actually holds the data, so the same tool works across releases.
Related MCP server: elasticsearch-mcp
Install
uv syncConfigure
Copy .env.example to .env and fill it in, or set the variables in your MCP
client config.
Variable | Required | Default | Purpose |
| for Manager tools | — | e.g. |
| for Manager tools | — | API credentials |
| for alert tools | — | e.g. |
| for alert tools | — | Indexer credentials |
| no | — | Path to your Wazuh root CA (preferred over disabling TLS) |
| no |
| Set |
| no |
| Enables agent restart, scans, active response |
| no |
| Per-request timeout, seconds |
| no |
| Ceiling on any single result set |
| no |
| Alert index pattern |
| no |
| Vulnerability state index |
Either backend can be configured alone. Tools needing a missing backend fail with a message naming the exact variables to set, rather than a generic error.
Least-privilege credentials
Create a dedicated Wazuh API user with a read-only RBAC role instead of reusing
wazuh-wui. If you never intend to enable WAZUH_ALLOW_WRITE, the role needs
only read actions — the server's read-only default and the API's own RBAC then
reinforce each other.
Transports
stdio (default) for a local client — no token, no network surface.
streamable HTTP for remote clients, authenticated with a bearer token:
WAZUH_TRANSPORT=http WAZUH_PUBLIC_URL=https://wazuh.example.com/mcp \
WAZUH_AUTH_TOKENS=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))') \
uv run wazuh-mcpVariable | Default | Purpose |
|
|
|
|
| Bind address; leave on loopback behind a proxy |
|
| Bind port |
|
| URL path to serve on |
| — | Required for |
|
| Advertised as |
| — | Required for |
| from | Accepted |
The HTTP transport fails closed: it will not start without a token of at
least 32 characters, or without WAZUH_PUBLIC_URL. Requests arrive as
Authorization: Bearer <token>; anything else gets a 401 carrying the
protected-resource metadata URL. DNS-rebinding protection is on, so the Host
header must appear in the allowlist — a forged one gets 421.
Public (unauthenticated) paths are exactly the RFC 9728 metadata at
/.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp.
This server is not an OAuth authorization server: clients must send the static
token themselves (e.g. npx mcp-remote <url> --header "Authorization: Bearer $TOKEN").
A bare GET /mcp with a valid token but no Mcp-Session-Id returns 400 — that is
the SDK's stateful Streamable HTTP behaviour (GET is only for resuming a session's
SSE stream), not a bug. Without a token it returns 401.
Terminate TLS in front of it. A bearer token over plain HTTP is sent in clear text, and binding to anything other than loopback logs a warning saying so. See deploy/DEPLOY.md for a systemd + nginx deployment, including the point that running on the Wazuh host lets you close ports 55000 and 9200 entirely.
Connect it
Claude Code
claude mcp add wazuh --env WAZUH_API_URL=https://wazuh.example.com:55000 --env WAZUH_API_USER=wazuh-mcp --env WAZUH_API_PASSWORD=secret --env WAZUH_INDEXER_URL=https://wazuh.example.com:9200 --env WAZUH_INDEXER_USER=wazuh-mcp --env WAZUH_INDEXER_PASSWORD=secret -- uv run --directory /Users/lema/Projects/wazuh-mcp wazuh-mcpClaude Desktop / any stdio client
{
"mcpServers": {
"wazuh": {
"command": "uv",
"args": ["run", "--directory", "/Users/lema/Projects/wazuh-mcp", "wazuh-mcp"],
"env": {
"WAZUH_API_URL": "https://wazuh.example.com:55000",
"WAZUH_API_USER": "wazuh-mcp",
"WAZUH_API_PASSWORD": "secret",
"WAZUH_INDEXER_URL": "https://wazuh.example.com:9200",
"WAZUH_INDEXER_USER": "wazuh-mcp",
"WAZUH_INDEXER_PASSWORD": "secret"
}
}
}
}Tools
Health and operations
Tool | What it answers |
| One call: manager version, daemon states, cluster, agent counts, Indexer health. Start here. |
| Node roles, sync state, healthcheck detail |
|
|
| analysisd queue pressure and dropped events, remoted counters, alert volume |
| The running |
| Read-only escape hatch for any Manager API endpoint |
Agents
Tool | What it answers |
| Filter by status, group, OS, version, name, or a raw |
| One endpoint in full: state, OS, hardware, package count |
| Fleet health: status mix, OS spread, outdated, ungrouped |
| Groups and their members |
| The config an agent actually loaded (did the group change land?) |
| Write. Restart agents |
Alerts (Indexer)
Tool | What it answers |
| The main alert query: time window, severity, agent, rule, MITRE, source IP, free text |
| "Top N by X" — one or two grouping levels, done server-side |
| Volume over time with automatic bucket sizing and peak detection |
| Raw OpenSearch DSL, restricted to |
| What data exists and how far back |
Vulnerabilities
Tool | What it answers |
| CVEs by agent, severity, CVE ID, package, CVSS floor |
| Exposure rollup: severity mix, worst hosts, most widespread CVEs |
Detection content
Tool | What it answers |
| Search the ruleset, including by compliance control |
| One rule plus its XML definition |
| Valid rule groups, or every control in a framework |
| How a log source is being parsed |
| ATT&CK techniques, tactics, groups, software, mitigations |
| CDB lookup lists and their contents |
Posture and inventory
Tool | What it answers |
| CIS-style hardening scores per policy, worst first |
| Individual checks with remediation text; defaults to failures |
| File integrity state, hashes, change counts |
| Legacy rootkit / policy-monitoring findings |
| Packages, processes, ports, interfaces, hardware, hotfixes |
| Fleet-wide package search — "who has log4j?" |
| Write. Trigger a FIM scan now |
Reporting
wazuh_generate_report returns structured data and a rendered markdown
report. Types: executive_summary, threat_activity, agent_health,
vulnerability_exposure, compliance (PCI DSS / GDPR / HIPAA / NIST 800-53 /
TSC), file_integrity, authentication.
Active response
wazuh_active_response — Write, destructive. Runs firewall-drop,
disable-account, host-deny and friends on named agents. Marked destructive
in its tool annotations so clients prompt before use.
Conventions
Time — relative (
30m,24h,7d) or ISO-8601. Alert queries default to 24 hours; reports to 7 days.Severity — maps to Wazuh rule levels: critical 15+, high 12–14, medium 7–11, low 4–6, info 0–3.
Agent IDs — zero-padded to three digits automatically;
000is the manager itself.Paging — list results carry
total_matchingand, when more exist,next_offset.
Safety
Read-only by default. Every state-changing tool checks
WAZUH_ALLOW_WRITEbefore issuing any request, and is annotated withread_only_hint=false/destructive_hint=true.Credential endpoints are blocked.
wazuh_api_requestrefuses/agents/{id}/keyand the authentication endpoint, so agent keys and API tokens cannot be pulled into a model's context.Index access is namespaced. Raw Indexer queries are restricted to
wazuh-*prefixes, with path-traversal patterns rejected, so a query cannot reach unrelated indices sharing the cluster.Output is bounded. Long strings are truncated and large containers summarised, so one broad query cannot flood the context window.
Development
uv run pytestuv run ruff check .The suite runs against a mocked Wazuh (respx) and covers the JWT
refresh-on-401 path, envelope handling, .keyword aggregation fallback,
4.8 vulnerability routing, write gating, index guards and report rendering.
Verified end to end against a live Wazuh 4.14.7 deployment. Version-specific behaviour the mocks alone would have missed, now covered by regression tests:
/agents/summary/statusnests counts underconnection/configuration; older releases returned one flat mapping. Both are parsed.wazuh-agentlessd,wazuh-csyslogd,wazuh-maild,wazuh-reportdandwazuh-clusterdare stopped in a healthy default install, so only stopped core daemons are reported as a problem.vulnerability.severityis the literal"-"for unscored CVEs — around a fifth of findings on a real host. It is relabelledUntriagedrather than dropped, so severity breakdowns reconcile with the total.The MITRE
*_idsparameters match internal STIX ids, not ATT&CK numbers. Lookups queryexternal_id/idsoT1595andattack-pattern--<uuid>both work.
Tests construct settings with _env_file=None and strip inherited WAZUH_*
variables, so a populated .env cannot leak into them and quietly satisfy the
assertions that check for missing configuration.
Available Tools
34 toolswazuh_active_responseRun an active-response commandADestructive
Execute an active-response command on agents — blocking an IP with firewall-drop, disabling an account, null-routing a host. This changes the state of production endpoints and can cut off network access, so it requires WAZUH_ALLOW_WRITE=true and should be confirmed with a human before use.
Inputs: command (required), agent_ids (required), custom, arguments. Returns: object
wazuh_agent_configRead an agent's applied configurationARead-onlyIdempotent
Fetch the configuration a running agent has actually loaded for one module — useful for confirming a group change or centralised config reached the endpoint. Common pairs: component='syscheck' configuration='syscheck', component='wmodules' configuration='wmodules', component='agent' configuration='client'.
Inputs: agent_id (required), component (required), configuration (required). Returns: object
wazuh_agent_inventoryRead an agent's system inventoryARead-onlyIdempotent
Read collected inventory from one endpoint: installed packages, running processes, listening ports, network interfaces and addresses, hardware, OS or Windows hotfixes. Use it for questions like 'what is listening on this host', 'is package X installed', or 'what patches are missing'.
Inputs: agent_id (required), component (required), sort, limit, +3 more. Returns: object
wazuh_agent_summaryFleet health summaryARead-onlyIdempotent
Aggregate health of the whole agent fleet: connection-state counts, OS distribution, agents on outdated versions and agents with no group. The fastest way to answer 'how healthy is my deployment'.
Inputs: no named parameters. Returns: object
wazuh_alert_statsAggregate alerts by fieldARead-onlyIdempotent
Group alerts by one or two fields and return counts — the tool for 'top 10 rules today', 'which agents are noisiest', 'alert counts by MITRE tactic', or 'top source IPs per agent'. Far cheaper than fetching alerts and counting them yourself.
Inputs: end, top, text, start, +7 more. Returns: object
wazuh_alert_timelineAlert volume over timeARead-onlyIdempotent
Bucket alert counts into time intervals to show trend and spikes — 'was there a spike overnight', 'alert volume per hour this week'. Optionally splits each interval by a field such as severity or agent.
Inputs: end, text, start, agent_id, +6 more. Returns: object
wazuh_api_requestCall any read-only Manager API endpointARead-onlyIdempotent
Escape hatch for Manager API endpoints without a dedicated tool — for example /agents/stats/distinct, /tasks/status, /security/users, /overview/agents, or /experimental/* inventory endpoints. GET only, so it cannot change state. Prefer the purpose-built tools when one fits; they shape their output for readability.
Inputs: path (required), params. Returns: object
wazuh_cdb_listsList CDB listsBRead-onlyIdempotent
List the CDB (constant database) lists used by rules for lookups such as known-bad IPs, allowed users or audit keys, optionally including their contents.
Inputs: limit, offset, filename, include_contents. Returns: object
wazuh_cluster_statusCluster nodes and health checkARead-onlyIdempotent
Detailed cluster view: whether clustering is enabled, each node's role and address, and the manager's own healthcheck output including per-node sync status and agent distribution.
Inputs: no named parameters. Returns: object
wazuh_fim_findingsFile integrity monitoring findingsARead-onlyIdempotent
Query File Integrity Monitoring (syscheck) state for an agent: which monitored files and registry keys exist, their hashes, permissions and how many times they have changed. Use it to answer 'was this binary modified' or 'what changed in /etc'.
Inputs: agent_id (required), limit, offset, search, +4 more. Returns: object
wazuh_find_softwareFind software across the fleetARead-onlyIdempotent
Search for a package across every agent at once — the tool for vulnerability response questions like 'which hosts have log4j installed' or 'who is still on OpenSSL 1.1.1'. Returns the matching package and version per agent.
Inputs: package (required), limit, version, agent_limit. Returns: object
wazuh_generate_reportGenerate a Wazuh reportARead-onlyIdempotent
Build a ready-to-share report by combining several Wazuh sources into one narrative with a markdown rendering. Report types: executive_summary (posture overview for leadership), threat_activity (top threats, MITRE breakdown, attacking IPs), agent_health (connectivity and version drift), vulnerability_exposure (CVE exposure by severity and host), compliance (control coverage for a framework), file_integrity (FIM change activity), authentication (login failures and brute-force patterns). Use this instead of stitching many tool calls together by hand.
Inputs: end, top, start, agent_id, +2 more. Returns: object
wazuh_get_agentGet one agent in detailARead-onlyIdempotent
Full picture of a single agent: registration and connection state, operating system, hardware, group membership and installed-package count. Start here when investigating a specific endpoint.
Inputs: agent_id (required). Returns: object
wazuh_get_ruleGet one rule with full detailARead-onlyIdempotent
Fetch a single rule including its full XML definition, so you can explain exactly what conditions trigger it and what it is mapped to.
Inputs: rule_id (required). Returns: object
wazuh_healthOverall deployment healthARead-onlyIdempotent
One-call situational awareness: manager version and uptime, the state of every Wazuh daemon, cluster status, agent connection counts and Indexer cluster health. Call this first when asked 'is Wazuh healthy' or when starting an investigation.
Inputs: no named parameters. Returns: object
wazuh_indexer_queryRun a raw Indexer queryARead-onlyIdempotent
Escape hatch: send a raw OpenSearch query DSL body to a Wazuh index for anything the purpose-built alert tools cannot express — unusual aggregations, scripted fields, composite queries. Restricted to wazuh-* indices and read-only _search.
Inputs: body (required), index. Returns: object
wazuh_list_agentsList Wazuh agentsARead-onlyIdempotent
List and filter agents enrolled with the Wazuh manager. Use this to answer 'which endpoints are disconnected', 'what agents are in group X', or 'which agents run an outdated version'. Supports server-side filtering, sorting and paging.
Inputs: ip, name, sort, group, +7 more. Returns: object
wazuh_list_decodersSearch log decodersARead-onlyIdempotent
Search the decoders that parse raw logs into fields. Use this when an alert's fields look wrong or absent, to see how a log source is being parsed.
Inputs: limit, offset, search, status, +2 more. Returns: object
wazuh_list_groupsList agent groupsARead-onlyIdempotent
List configured agent groups with their member counts and configuration checksums. Pass a group name to list its members instead.
Inputs: group, limit, offset. Returns: object
wazuh_list_indicesList Wazuh indicesARead-onlyIdempotent
List the wazuh-* indices with health, document counts and sizes, plus Indexer cluster health. Use this to confirm what data exists and how far back it goes before querying.
Inputs: pattern. Returns: object
wazuh_list_rulesSearch detection rulesARead-onlyIdempotent
Search the manager's ruleset. Use this to explain why an alert fired, to find every rule covering a compliance control ('which rules map to PCI DSS 10.2.4'), or to audit which high-severity rules are enabled.
Inputs: sort, group, level, limit, +8 more. Returns: object
wazuh_manager_configRead manager configurationARead-onlyIdempotent
Read the manager's running ossec.conf configuration, optionally narrowed to one section. Use this to confirm what is actually enabled — which modules, integrations, log sources or remote settings.
Inputs: field, section. Returns: object
wazuh_manager_logsRead manager logsARead-onlyIdempotent
Read and filter ossec.log entries from the manager. Use this to diagnose ingestion problems, integration failures or daemon errors — filter to level='error' to see only what is broken.
Inputs: tag, level, limit, offset, +2 more. Returns: object
wazuh_manager_statsManager throughput statisticsARead-onlyIdempotent
Event-processing statistics from the manager: analysisd queue usage and event rates, remoted reception counts, or hourly/weekly alert volumes. Use analysisd stats to spot dropped events and queue saturation.
Inputs: kind. Returns: object
wazuh_mitreQuery the MITRE ATT&CK catalogueARead-onlyIdempotent
Look up MITRE ATT&CK techniques, tactics, groups, software or mitigations from the manager's bundled catalogue. Use it to expand a technique ID seen in an alert into its description, tactics and mitigations.
Inputs: ids, limit, offset, search, +1 more. Returns: object
wazuh_restart_agentsRestart Wazuh agentsADestructive
Restart one or more agents. This interrupts monitoring on the target endpoints while they come back up, and requires WAZUH_ALLOW_WRITE=true.
Inputs: agent_ids (required). Returns: object
wazuh_rootcheckRootcheck / policy-monitoring findingsARead-onlyIdempotent
Read rootcheck findings for an agent — rootkit signatures, hidden processes and legacy policy-monitoring hits. Note this is Wazuh's older assessment module; SCA (wazuh_sca_checks) is the modern equivalent and usually more useful.
Inputs: agent_id (required), limit, offset, search, +1 more. Returns: object
wazuh_rule_groupsList rule groups and compliance controlsARead-onlyIdempotent
Enumerate the rule groups in the ruleset, or every value present for one compliance framework. Useful for discovering valid filter values before calling wazuh_list_rules or wazuh_search_alerts.
Inputs: limit, requirement. Returns: object
wazuh_run_scanTrigger a FIM or SCA scanA
Ask agents to start a syscheck (FIM) scan now instead of waiting for the schedule. This puts load on the target endpoints and requires WAZUH_ALLOW_WRITE=true.
Inputs: agent_ids (required). Returns: object
wazuh_sca_checksSCA checks within a policyARead-onlyIdempotent
List the individual configuration checks in one SCA policy, including the remediation text for each. Filter to result='failed' to get an actionable hardening list for a host.
Inputs: agent_id (required), policy_id (required), limit, offset, +3 more. Returns: object
wazuh_sca_policiesSCA policy scores for an agentARead-onlyIdempotent
List an agent's Security Configuration Assessment policies with pass/fail counts and hardening scores — CIS benchmarks and similar. Use this to answer 'how well hardened is this host' before drilling into individual failed checks.
Inputs: agent_id (required). Returns: object
wazuh_search_alertsSearch Wazuh alertsARead-onlyIdempotent
Search security alerts in the Wazuh Indexer over a time window. This is the main tool for questions like 'show me critical alerts in the last hour', 'what fired on server-db-01 yesterday', 'find SSH brute force attempts', or 'alerts matching MITRE T1110'. Returns a compact projection of each alert by default.
Inputs: end, text, limit, start, +12 more. Returns: object
wazuh_vulnerabilitiesList detected vulnerabilitiesARead-onlyIdempotent
List CVEs Wazuh has detected on endpoints, filterable by agent, severity, CVE ID and package. Answers 'what critical CVEs do we have', 'is CVE-2024-3094 anywhere in the estate', or 'which vulnerable packages are on this host'. Works on both 4.8+ (Indexer state) and earlier (Manager API) deployments.
Inputs: cve, limit, offset, package, +3 more. Returns: object
wazuh_vulnerability_summarySummarise vulnerability exposureARead-onlyIdempotent
Aggregate vulnerability exposure across the fleet: counts by severity, the most affected agents, the most common CVEs and the worst offending packages. Use this for exposure reporting and to decide where to look in detail.
Inputs: top, agent_id, min_severity. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 34 tools
Most tools target a distinct resource (alerts, agents, rules, SCA, FIM, vulnerabilities), but several overlap: wazuh_health, wazuh_cluster_status, and wazuh_agent_summary all describe health/status, and wazuh_search_alerts, wazuh_alert_stats, wazuh_alert_timeline, and wazuh_indexer_query all query alert data. The descriptions are clear enough to avoid most misselections, but the boundaries are not crisp.
All names share the wazuh_ prefix and snake_case, but the action pattern is inconsistent: some are verb-first (search_alerts, list_agents, generate_report), some are bare nouns (health, rootcheck, vulnerabilities), and some are noun phrases (cluster_status, agent_summary). A uniform verb_noun convention would make the set more predictable.
34 tools is well above the 25+ threshold and makes the surface feel heavy; several status/stat tools could be consolidated and two escape hatches cover long-tail needs. Wazuh is a broad platform, but this count will increase token overhead and selection difficulty.
The set covers the main Wazuh operations well: alert search, agent health, SCA/FIM/inventory, vulnerability lookup, rule/decoder reference, reporting, and active response. Minor gaps exist (no agent-group assignment, no rule/decoder editing, no alert triage/acknowledge), but the read-only API escape hatch and the breadth of purpose-built tools keep workflows from hitting dead ends.
Maintenance
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Remote MCP for 1,500+ APIs. Vault-managed credentials; OAuth or API key. Search, load, and execute.
Scans remote MCP servers for protocol, security, and TLS issues; exposes scan tools via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables integration between Wazuh security platform and AI applications through the MCP framework, providing tools for security analysis, agent management, and system monitoring.4MIT
- AlicenseAqualityDmaintenanceEnables any MCP-compatible agent to query, diagnose, map, and operate Elasticsearch or OpenSearch clusters via REST, with read-only defaults and layered safety controls.34Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables local MCP access to attach to isolated backend environments, monitor runtime health/logs, check security posture, manage snapshots and diffs, audit events, and view sanitized remote inventory.4 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables incident responders to query and correlate observability and DevOps evidence across Grafana, Prometheus, Loki, Uptime Kuma, CloudWatch, IAM, and PostHog from a local MCP client, with bounded reads and redacted audit records.MIT