Skip to main content
Glama

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 sync

Configure

Copy .env.example to .env and fill it in, or set the variables in your MCP client config.

Variable

Required

Default

Purpose

WAZUH_API_URL

for Manager tools

—

e.g. https://wazuh.example.com:55000

WAZUH_API_USER / WAZUH_API_PASSWORD

for Manager tools

—

API credentials

WAZUH_INDEXER_URL

for alert tools

—

e.g. https://wazuh.example.com:9200

WAZUH_INDEXER_USER / WAZUH_INDEXER_PASSWORD

for alert tools

—

Indexer credentials

WAZUH_CA_BUNDLE

no

—

Path to your Wazuh root CA (preferred over disabling TLS)

WAZUH_VERIFY_SSL

no

true

Set false only for self-signed labs

WAZUH_ALLOW_WRITE

no

false

Enables agent restart, scans, active response

WAZUH_TIMEOUT

no

30

Per-request timeout, seconds

WAZUH_MAX_RESULTS

no

500

Ceiling on any single result set

WAZUH_ALERTS_INDEX

no

wazuh-alerts-*

Alert index pattern

WAZUH_VULNERABILITY_INDEX

no

wazuh-states-vulnerabilities-*

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-mcp

Variable

Default

Purpose

WAZUH_TRANSPORT

stdio

stdio or http

WAZUH_BIND_HOST

127.0.0.1

Bind address; leave on loopback behind a proxy

WAZUH_BIND_PORT

8080

Bind port

WAZUH_HTTP_PATH

/mcp

URL path to serve on

WAZUH_PUBLIC_URL

—

Required for http; the URL clients reach

WAZUH_ISSUER_URL

public_url

Advertised as authorization_servers in the resource metadata

WAZUH_AUTH_TOKENS

—

Required for http; comma-separated to rotate

WAZUH_ALLOWED_HOSTS

from public_url

Accepted Host values

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-mcp

Claude 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

wazuh_health

One call: manager version, daemon states, cluster, agent counts, Indexer health. Start here.

wazuh_cluster_status

Node roles, sync state, healthcheck detail

wazuh_manager_logs

ossec.log filtered by level/daemon, or a per-daemon error summary

wazuh_manager_stats

analysisd queue pressure and dropped events, remoted counters, alert volume

wazuh_manager_config

The running ossec.conf, by section

wazuh_api_request

Read-only escape hatch for any Manager API endpoint

Agents

Tool

What it answers

wazuh_list_agents

Filter by status, group, OS, version, name, or a raw q filter

wazuh_get_agent

One endpoint in full: state, OS, hardware, package count

wazuh_agent_summary

Fleet health: status mix, OS spread, outdated, ungrouped

wazuh_list_groups

Groups and their members

wazuh_agent_config

The config an agent actually loaded (did the group change land?)

wazuh_restart_agents

Write. Restart agents

Alerts (Indexer)

Tool

What it answers

wazuh_search_alerts

The main alert query: time window, severity, agent, rule, MITRE, source IP, free text

wazuh_alert_stats

"Top N by X" — one or two grouping levels, done server-side

wazuh_alert_timeline

Volume over time with automatic bucket sizing and peak detection

wazuh_indexer_query

Raw OpenSearch DSL, restricted to wazuh-*

wazuh_list_indices

What data exists and how far back

Vulnerabilities

Tool

What it answers

wazuh_vulnerabilities

CVEs by agent, severity, CVE ID, package, CVSS floor

wazuh_vulnerability_summary

Exposure rollup: severity mix, worst hosts, most widespread CVEs

Detection content

Tool

What it answers

wazuh_list_rules

Search the ruleset, including by compliance control

wazuh_get_rule

One rule plus its XML definition

wazuh_rule_groups

Valid rule groups, or every control in a framework

wazuh_list_decoders

How a log source is being parsed

wazuh_mitre

ATT&CK techniques, tactics, groups, software, mitigations

wazuh_cdb_lists

CDB lookup lists and their contents

Posture and inventory

Tool

What it answers

wazuh_sca_policies

CIS-style hardening scores per policy, worst first

wazuh_sca_checks

Individual checks with remediation text; defaults to failures

wazuh_fim_findings

File integrity state, hashes, change counts

wazuh_rootcheck

Legacy rootkit / policy-monitoring findings

wazuh_agent_inventory

Packages, processes, ports, interfaces, hardware, hotfixes

wazuh_find_software

Fleet-wide package search — "who has log4j?"

wazuh_run_scan

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; 000 is the manager itself.

  • Paging — list results carry total_matching and, when more exist, next_offset.

Safety

  • Read-only by default. Every state-changing tool checks WAZUH_ALLOW_WRITE before issuing any request, and is annotated with read_only_hint=false / destructive_hint=true.

  • Credential endpoints are blocked. wazuh_api_request refuses /agents/{id}/key and 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 pytest
uv 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/status nests counts under connection / configuration; older releases returned one flat mapping. Both are parsed.

  • wazuh-agentlessd, wazuh-csyslogd, wazuh-maild, wazuh-reportd and wazuh-clusterd are stopped in a healthy default install, so only stopped core daemons are reported as a problem.

  • vulnerability.severity is the literal "-" for unscored CVEs — around a fifth of findings on a real host. It is relabelled Untriaged rather than dropped, so severity breakdowns reconcile with the total.

  • The MITRE *_ids parameters match internal STIX ids, not ATT&CK numbers. Lookups query external_id / id so T1595 and attack-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 tools
wazuh_active_responseRun an active-response commandA
Destructive

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 configurationA
Read-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 inventoryA
Read-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 summaryA
Read-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 fieldA
Read-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 timeA
Read-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 endpointA
Read-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 listsB
Read-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 checkA
Read-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 findingsA
Read-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 fleetA
Read-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 reportA
Read-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 detailA
Read-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 detailA
Read-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 healthA
Read-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 queryA
Read-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 agentsA
Read-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 decodersA
Read-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 groupsA
Read-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 indicesA
Read-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 rulesA
Read-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 configurationA
Read-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 logsA
Read-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 statisticsA
Read-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 catalogueA
Read-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 agentsA
Destructive

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 findingsA
Read-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 controlsA
Read-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 policyA
Read-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 agentA
Read-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 alertsA
Read-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 vulnerabilitiesA
Read-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 exposureA
Read-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

    A3.6/5.0

    Scored across 34 tools

    Disambiguation3/5

    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.

    Naming Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables integration between Wazuh security platform and AI applications through the MCP framework, providing tools for security analysis, agent management, and system monitoring.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables any MCP-compatible agent to query, diagnose, map, and operate Elasticsearch or OpenSearch clusters via REST, with read-only defaults and layered safety controls.
      34
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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