Wazuh MCP Server

A production-ready Model Context Protocol (MCP) server for seamless integration between Wazuh SIEM and Large Language Models (LLMs).

Why? Combine the power of Wazuh's comprehensive security monitoring with the reasoning capabilities of large language models—enabling natural language queries and intelligent analysis of your security data.

---

✨ Key Features

• 🚀 Production-ready: Proper package structure, logging, error handling, and configuration management
• 🔐 Secure: JWT token management with automatic refresh
• 🌐 HTTP/2 Support: Built on modern async HTTP client with connection pooling
• 📊 Comprehensive API: Access Wazuh agents, authentication, and more
• 🎛️ Configurable: Environment variables, CLI arguments, and fine-grained tool filtering
• 📦 Pip installable: Install directly from GitHub releases or source

---

Table of Contents

• Quick Start
• Installation
• Configuration
• Usage
• Available Tools
• Development
• CI/CD
• Deployment
• Security
• Contributing
• License

---

Quick Start

1. Install

From GitHub (Recommended)

python -m venv .venv && source .venv/bin/activate
pip install git+https://github.com/socfortress/wazuh-mcp-server.git

From Release Artifacts

1. Go to the Releases page
2. Download the latest .whl file
3. Install with:

pip install wazuh_mcp_server-*.whl

From Build Artifacts (Latest Build)

1. Go to the Actions tab
2. Click on the latest successful workflow run
3. Download the python-package-distributions artifact
4. Extract and install:

pip install wazuh_mcp_server-*.whl

2. Configure Environment

Create a .env file in your project directory:

# Wazuh Manager Configuration
WAZUH_PROD_URL=https://your-wazuh-manager:55000
WAZUH_PROD_USERNAME=your-username
WAZUH_PROD_PASSWORD=your-password
WAZUH_PROD_SSL_VERIFY=false
WAZUH_PROD_TIMEOUT=30

# MCP Server Configuration
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000

# Logging Configuration
LOG_LEVEL=INFO

# Tool Filtering (optional)
# WAZUH_DISABLED_TOOLS=DeleteAgentTool,RestartManagerTool
# WAZUH_DISABLED_CATEGORIES=dangerous,write
# WAZUH_READ_ONLY=false

3. Run the Server

# Using the CLI command
wazuh-mcp-server

# Or using the Python module
python -m wazuh_mcp_server

# Streamable HTTP for networked clients (requires MCP_AUTH_TOKEN)
MCP_AUTH_TOKEN=$(openssl rand -hex 32) wazuh-mcp-server --transport http --host 0.0.0.0 --port 8000

By default the server speaks MCP over stdio, for clients that launch it as a subprocess (.mcp.json). With --transport http (or MCP_TRANSPORT=http) it serves streamable HTTP at http://<host>:<port>/mcp:

• Every request must carry Authorization: Bearer <MCP_AUTH_TOKEN>. The server refuses to start in HTTP mode without a token.
• GET /healthz is unauthenticated, for container health checks.

Example from Pydantic AI:

from pydantic_ai.mcp import MCPToolset

wazuh = MCPToolset("http://wazuh-mcp:8000/mcp", id="wazuh", headers={"Authorization": f"Bearer {token}"})
async with wazuh:
    agents = await wazuh.direct_call_tool("GetAgentsTool", {"args": {"q": "id=021"}})

---

Installation

Requirements

• Python 3.11 or higher
• Access to a Wazuh Manager instance
• Network connectivity to your Wazuh Manager

Development Installation

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

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks (optional)
pre-commit install

---

Configuration

Environment Variables

Variable	Description	Default	Required
WAZUH_PROD_URL	Wazuh Manager API URL	None	✅
WAZUH_PROD_USERNAME	Wazuh username	None	✅
WAZUH_PROD_PASSWORD	Wazuh password	None	✅
WAZUH_PROD_SSL_VERIFY	SSL verification	true	❌
WAZUH_PROD_TIMEOUT	Request timeout (seconds)	30	❌
MCP_TRANSPORT	stdio or http	stdio	❌
MCP_SERVER_HOST	HTTP bind host	127.0.0.1	❌
MCP_SERVER_PORT	HTTP port	8000	❌
MCP_AUTH_TOKEN	Bearer token for the HTTP transport	None	✅ for http
LOG_LEVEL	Logging level	INFO	❌
WAZUH_DISABLED_TOOLS	Comma-separated list of disabled tools	None	❌
WAZUH_DISABLED_CATEGORIES	Comma-separated list of disabled categories	None	❌
WAZUH_READ_ONLY	Don't register tools that change state on the manager. All current tools only read; new tools must be classified in TOOL_META, and unclassified tools count as writes.	false	❌

Tool categories for WAZUH_DISABLED_CATEGORIES: auth, agents, rules, sca.

Output and errors

• Output. Responses are compact JSON, capped at MCP_MAX_OUTPUT_CHARS (default 32000). When a response is too large, whole affected_items are dropped and a truncated object reports returned_items, original_items, total_affected_items and original_chars. Lower limit, select fewer fields, or page with offset.
• Limits. List tools default to limit: 50.
• Errors. Failures, including Wazuh "error": 1 responses, are returned as MCP tool errors (isError: true), not as normal text.

Docker

docker build -t wazuh-mcp-server .
docker run --env-file .env -p 127.0.0.1:8000:8000 wazuh-mcp-server   # HTTP on :8000, needs MCP_AUTH_TOKEN

The image runs as a non-root user and has a health check on /healthz. Images are published to ghcr.io/socfortress/wazuh-mcp-server:

• main and sha-… on every push to main
• X.Y.Z and X.Y for vX.Y.Z tags

See CHANGELOG.md.

CLI Options

wazuh-mcp-server --help

Available options:

• --transport: stdio or http (default: MCP_TRANSPORT, else stdio)
• --host: HTTP bind host (default: MCP_SERVER_HOST, else 127.0.0.1)
• --port: HTTP port (default: MCP_SERVER_PORT, else 8000)
• --log-level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• --wazuh-url: Wazuh Manager URL (overrides env var)
• --wazuh-username: Wazuh username (overrides env var)
• --wazuh-password: Wazuh password (overrides env var)
• --no-ssl-verify: Disable SSL certificate verification

---

Usage

Basic Usage

from wazuh_mcp_server import Config, create_server

# Create server with environment configuration
config = Config.from_env()
server = create_server(config)

# Start the server
server.start()

Custom Configuration

from wazuh_mcp_server.config import WazuhConfig, ServerConfig, Config

# Create custom configuration
wazuh_config = WazuhConfig(
    url="https://your-wazuh-manager:55000",
    username="admin",
    password="password",
    ssl_verify=False
)

server_config = ServerConfig(
    host="0.0.0.0",
    port=8080,
    log_level="DEBUG"
)

config = Config(wazuh=wazuh_config, server=server_config)
server = create_server(config)

Integration with LangChain

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import AgentType, initialize_agent

async def main():
    # Initialize LLM with hardcoded API key
    model = ChatOpenAI(
        model="gpt-4",
        api_key="sk-your-api-key"  # <-- replace with your actual key
    )

    # Connect to Wazuh MCP server
    client = MultiServerMCPClient({
        "wazuh-mcp-server": {
            "transport": "sse",
            "url": "http://127.0.0.1:8000/sse/",
        }
    })

    # Get tools and create agent
    tools = await client.get_tools()
    agent = initialize_agent(
        tools=tools,
        llm=model,
        agent=AgentType.OPENAI_FUNCTIONS,
        verbose=True
    )

    # Query your Wazuh data
    response = await agent.ainvoke({
        "input": "Show me all active agents and their status"
    })
    print("Active agents response:")
    print(response)

    # Get network ports information
    ports_response = await agent.ainvoke({
        "input": "Show me all listening TCP ports on agent 000"
    })
    print("Ports response:")
    print(ports_response)

if __name__ == "__main__":
    asyncio.run(main())

---

Available Tools

The server exposes the following MCP tools:

1. AuthenticateTool

• Purpose: Force JWT token refresh from Wazuh Manager
• Parameters: None
• Usage: Ensures fresh authentication tokens

2. GetAgentsTool

• Purpose: Retrieve agents from Wazuh Manager with filtering
• Parameters:
  • status (optional): Filter by agent status (e.g., ["active"])
  • limit (optional): Maximum number of agents to return (default: 500)
  • offset (optional): Offset for pagination (default: 0)

3. GetAgentPortsTool

• Purpose: Get network ports information from a specific agent using syscollector
• Parameters:
  • agent_id (required): Agent ID to get ports from
  • limit (optional): Maximum number of ports to return (default: 500)
  • offset (optional): Offset for pagination (default: 0)
  • protocol (optional): Filter by protocol (tcp, udp)
  • local_ip (optional): Filter by local IP address
  • local_port (optional): Filter by local port
  • remote_ip (optional): Filter by remote IP address
  • state (optional): Filter by state (listening, established, etc.)
  • process (optional): Filter by process name
  • pid (optional): Filter by process ID
  • tx_queue (optional): Filter by tx_queue
  • sort (optional): Sort results by field(s)
  • search (optional): Search for elements containing the specified string
  • select (optional): Select which fields to return
  • q (optional): Query to filter results by
  • distinct (optional): Look for distinct values

4. GetAgentPackagesTool

• Purpose: Get installed packages information from a specific agent using syscollector
• Parameters:
  • agent_id (required): Agent ID to get packages from
  • limit (optional): Maximum number of packages to return (default: 500)
  • offset (optional): Offset for pagination (default: 0)
  • vendor (optional): Filter by package vendor
  • name (optional): Filter by package name
  • architecture (optional): Filter by package architecture
  • format (optional): Filter by package format (e.g., 'deb', 'rpm')
  • version (optional): Filter by package version
  • sort (optional): Sort results by field(s)
  • search (optional): Search for elements containing the specified string
  • select (optional): Select which fields to return
  • q (optional): Query to filter results by
  • distinct (optional): Look for distinct values

5. GetAgentProcessesTool

• Purpose: Get running processes information from a specific agent using syscollector
• Parameters:
  • agent_id (required): Agent ID to get processes from
  • limit (optional): Maximum number of processes to return (default: 500)
  • offset (optional): Offset for pagination (default: 0)
  • pid (optional): Filter by process PID
  • state (optional): Filter by process state
  • ppid (optional): Filter by process parent PID
  • egroup (optional): Filter by process egroup
  • euser (optional): Filter by process euser
  • fgroup (optional): Filter by process fgroup
  • name (optional): Filter by process name
  • nlwp (optional): Filter by process nlwp
  • pgrp (optional): Filter by process pgrp
  • priority (optional): Filter by process priority
  • rgroup (optional): Filter by process rgroup
  • ruser (optional): Filter by process ruser
  • sgroup (optional): Filter by process sgroup
  • suser (optional): Filter by process suser
  • sort (optional): Sort results by field(s)
  • search (optional): Search for elements containing the specified string
  • select (optional): Select which fields to return
  • q (optional): Query to filter results by
  • distinct (optional): Look for distinct values

6. ListRulesTool

• Purpose: List rules from Wazuh Manager with various filtering options
• Parameters:
  • rule_ids (optional): List of rule IDs to filter by
  • limit (optional): Maximum number of rules to return (default: 500)
  • offset (optional): Offset for pagination (default: 0)
  • select (optional): Select which fields to return
  • sort (optional): Sort results by field(s)
  • search (optional): Search for elements containing the specified string
  • q (optional): Query to filter results by
  • status (optional): Filter by status (enabled, disabled, all)
  • group (optional): Filter by rule group
  • level (optional): Filter by rule level (e.g., '4' or '2-4')
  • filename (optional): Filter by filename
  • relative_dirname (optional): Filter by relative directory name
  • pci_dss (optional): Filter by PCI_DSS requirement
  • gdpr (optional): Filter by GDPR requirement
  • gpg13 (optional): Filter by GPG13 requirement
  • hipaa (optional): Filter by HIPAA requirement
  • nist_800_53 (optional): Filter by NIST-800-53 requirement
  • tsc (optional): Filter by TSC requirement
  • mitre (optional): Filter by MITRE technique ID
  • distinct (optional): Look for distinct values

7. GetRuleFileContentTool

• Purpose: Get the content of a specific rule file from the ruleset
• Parameters:
  • filename (required): Filename of the rule file to get content from
  • raw (optional): Format response in plain text (default: false)
  • relative_dirname (optional): Filter by relative directory name

8. GetRuleFilesTool

• Purpose: Get a list of all rule files and their status from Wazuh Manager
• Parameters:
  • pretty (optional): Show results in human-readable format
  • wait_for_complete (optional): Disable timeout response
  • offset (optional): First element to return in the collection (default: 0)
  • limit (optional): Maximum number of elements to return (default: 500)
  • sort (optional): Sort the collection by a field or fields
  • search (optional): Look for elements containing the specified string
  • relative_dirname (optional): Filter by relative directory name
  • filename (optional): Filter by filename of one or more rule or decoder files
  • status (optional): Filter by list status (enabled, disabled, all)
  • q (optional): Query to filter results by
  • select (optional): Select which fields to return
  • distinct (optional): Look for distinct values

Example usage:

{"args": {"limit": 10, "status": "enabled"}}
{"args": {"filename": ["0020-syslog_rules.xml"]}}
{"args": {"search": "ruleset"}}

Returns:

• JSON list of rule files with their status and directory info

9. GetAgentSCATool

• Purpose: Get Security Configuration Assessment (SCA) results for a specific agent
• Parameters:
  • agent_id (required): Agent ID to get SCA results from
  • name (optional): Filter by policy name
  • description (optional): Filter by policy description
  • references (optional): Filter by references
  • limit (optional): Maximum number of SCA policies to return (default: 500)
  • offset (optional): Offset for pagination (default: 0)
  • sort (optional): Sort results by field(s)
  • search (optional): Search for elements containing the specified string
  • select (optional): Select which fields to return
  • q (optional): Query to filter results by
  • distinct (optional): Look for distinct values

---

Development

Setting up Development Environment

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

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=wazuh_mcp_server

# Run specific test file
pytest tests/test_client.py

# Run with verbose output
pytest -v

Building the Package

# Install build dependencies
pip install build twine

# Build the package
python -m build

# Check the package
twine check dist/*

# Test installation
pip install dist/*.whl

---

Continuous Integration

This project uses GitHub Actions for automated building and testing:

• Automatic builds: Every push to main and develop branches triggers a build
• Quality assurance: Comprehensive testing including linting, type checking, and unit tests
• Artifact publishing: Built packages are available as GitHub releases and workflow artifacts

Creating a Release

1. Create and push a git tag:

   git tag v1.0.0
   git push origin v1.0.0
   

2. The GitHub Action will automatically:

   • Build the package
   • Run all tests
   • Create a GitHub release with downloadable artifacts

Installing from CI Artifacts

Visit the Actions page and download the python-package-distributions artifact from any successful build.

---

Security Considerations

Credentials Management

• Never commit credentials: Use environment variables or secrets management
• Use strong passwords: Ensure Wazuh credentials are secure
• Rotate tokens: Regularly update API credentials

Network Security

• TLS/SSL: Always use HTTPS in production (WAZUH_PROD_SSL_VERIFY=true)
• Firewall rules: Restrict access to necessary ports only
• VPN/Private networks: Deploy in secured network environments

Access Control

• Least privilege: Create dedicated Wazuh users with minimal required permissions
• Read-only mode: Use WAZUH_READ_ONLY=true when write operations aren't needed
• Tool filtering: Disable unnecessary tools using WAZUH_DISABLED_TOOLS

Monitoring

• Logging: Enable appropriate log levels for monitoring
• Health checks: Implement monitoring of the MCP server endpoint
• Rate limiting: Consider implementing rate limiting for production deployments

---

Project Structure

wazuh-mcp-server/
├── wazuh_mcp_server/          # Main package
│   ├── __init__.py           # Package initialization
│   ├── __main__.py           # CLI entry point
│   ├── client.py             # Wazuh API client
│   ├── config.py             # Configuration management
│   ├── server.py             # MCP server implementation
│   └── exceptions.py         # Custom exceptions
├── tests/                    # Test suite
│   ├── conftest.py          # Test configuration
│   ├── test_client.py       # Client tests
│   ├── test_config.py       # Configuration tests
│   └── test_server.py       # Server tests
├── .github/workflows/        # GitHub Actions
│   └── publish.yml          # CI/CD pipeline
├── requirements.txt          # Dependencies
├── pyproject.toml           # Package configuration
├── .env.example             # Environment template
└── README.md                # This file

---

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Ensure tests pass: pytest
5. Check code quality: black ., isort ., flake8 .
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to your branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Guidelines

• Write tests for new functionality
• Follow existing code style and patterns
• Update documentation for new features
• Ensure all CI checks pass

---

License

This project is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only) - see the LICENSE file for details.

---

Changelog

v0.1.0 (Latest)

• Initial release
• Basic MCP server functionality
• Wazuh API integration with JWT authentication
• CLI interface with configuration options
• Docker and Kubernetes deployment support
• Comprehensive test suite
• GitHub Actions CI/CD pipeline

---

Support

• 📖 Documentation
• 🐛 Issues
• 🏢 SOCFortress

---

Made with ❤️ by SOCFortress