Wazuh MCP Server

A Python-based Model Context Protocol (MCP) server that exposes Wazuh security alerts and agent data to Claude Desktop and other AI assistants.

What This Does

This server connects to your Wazuh manager and provides Claude with 4 security tools:

Tool	Purpose	Example
critical_alerts	Get critical security events	"Show all critical alerts from today"
investigate_host	Deep dive into a specific system	"Investigate host web-server-01"
brute_force_detection	Find login attack attempts	"Which user failed authentication 20 times?"
security_summary	High-level overview	"Give me a security summary"

Quick Start (5 minutes)

1. Prerequisites

• Python 3.8+
• Wazuh manager running and accessible
• Claude Desktop installed
• Wazuh manager credentials (default: wazuh/wazuh)

2. Setup

# Clone or download this project
cd wazuh-mcp-server

# Run setup script
chmod +x setup.sh
./setup.sh

# Edit configuration
nano .env
# Update WAZUH_HOST to your Wazuh manager IP

3. Test Connection

# Activate environment
source venv/bin/activate

# Run connection test
python3 test_connection.py

You should see:

✓ Connected successfully!
✓ Found 5 agent(s)
✓ Found 23 alert(s)
✅ All tests passed!

4. Connect to Claude Desktop

Edit ~/.claude/claude_desktop_config.json:

macOS/Linux:

nano ~/.claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "wazuh": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/wazuh_mcp_server/server.py"],
      "env": {
        "WAZUH_HOST": "YOUR_WAZUH_IP",
        "WAZUH_USER": "wazuh",
        "WAZUH_PASS": "wazuh"
      }
    }
  }
}

Get absolute paths:

# Python path
which python3
# /Users/yourname/wazuh-mcp-server/venv/bin/python3

# Server path
pwd
# /Users/yourname/wazuh-mcp-server

5. Restart Claude Desktop

Close and reopen Claude Desktop. You should see "Wazuh Security Tools" in the Tools panel.

6. Try It Out

In Claude Desktop, try:

Show all critical alerts from the last 24 hours

Which hosts are experiencing high alert rates?

Investigate the database server

Detect any brute force attempts

Project Structure

wazuh-mcp-server/
├── server.py                 # Main MCP server (FastMCP)
├── wazuh_client.py          # Wazuh API client
├── requirements.txt         # Python dependencies
├── .env.example            # Configuration template
├── setup.sh                # Automated setup script
├── test_connection.py      # Connection verification
└── README.md               # This file

Configuration

Edit .env to customize:

WAZUH_HOST=192.168.1.100    # Your Wazuh manager IP
WAZUH_USER=wazuh            # API username
WAZUH_PASS=wazuh            # API password

Troubleshooting

"Connection refused" or "Network error"

# Check Wazuh manager is running
ssh user@wazuh-ip
sudo systemctl status wazuh-manager

# Verify API port is open
curl -k https://YOUR_WAZUH_IP:55000/security/user/authenticate \
  -u wazuh:wazuh

Claude Desktop doesn't show the tools

1. Check config syntax:

   python3 -c "import json; json.load(open(expanduser('~/.claude/claude_desktop_config.json')))"
   # Should return no errors
   

2. Check absolute paths:

   • Don't use ~/ or . in the config
   • Use full paths like /Users/name/...

3. Check logs:

   tail -f ~/Library/Logs/Claude/mcp-server.log  # macOS
   # or check Windows Event Viewer for Claude Desktop
   

4. Restart Claude Desktop:

   • Close completely
   • Reopen
   • Wait 5 seconds for MCP to connect

"Authentication failed"

# Verify credentials by testing directly
curl -k https://WAZUH_IP:55000/security/user/authenticate \
  -u wazuh:wazuh -X GET

# If 401: wrong credentials
# If 404: endpoint doesn't exist (Wazuh version issue)
# If timeout: firewall blocking

Advanced

Custom Wazuh Queries

The wazuh_client.py supports arbitrary queries:

from wazuh_client import WazuhClient

wazuh = WazuhClient("192.168.1.100")

# Search by rule group
alerts = wazuh.search_logs("rule.group=auth_failure")

# Search by agent
alerts = wazuh.search_logs("agent.name=web-server")

# Search by source IP
alerts = wazuh.search_logs("data.srcip=192.168.1.50")

# Search by user
alerts = wazuh.search_logs("data.user=root")

Adding More Tools

Edit server.py and add a new @app.tool():

@app.tool()
async def my_new_tool(param1: str) -> str:
    """
    Tool description shown to Claude.
    
    Args:
        param1: Parameter description
    
    Returns:
        JSON string with results
    """
    # Your code here
    return json.dumps({"result": "..."})

Production Considerations

• ✅ Use SSL certificates (not self-signed)
• ✅ Store credentials in HashiCorp Vault or AWS Secrets
• ✅ Rate limit MCP server to prevent abuse
• ✅ Enable audit logging on Wazuh API
• ✅ Create dedicated read-only API user
• ✅ Use network segmentation to isolate Wazuh

Security Notes

⚠️ For Development/Learning:

• Default credentials are wazuh/wazuh
• SSL verification disabled (dev mode)
• Credentials in plaintext in .env

For Production:

• Change Wazuh credentials immediately
• Use proper SSL certificates
• Store credentials in secure vault
• Create read-only API user with minimal permissions
• Audit all API access
• Network firewall rules to restrict access

API Reference

WazuhClient Methods

# Get alerts
wazuh.get_alerts(level=7, hours=24, limit=100, agent_id=None)

# Get all agents
wazuh.get_agents()

# Get agent details
wazuh.get_agent_details(agent_id="001")

# Search alerts
wazuh.search_logs(query="rule.id=100001", hours=24, limit=50)

# Get alert groups
wazuh.get_alert_groups(hours=24)

Learning Resources

• Wazuh Official Docs
• Wazuh API Reference
• Model Context Protocol
• FastMCP

Support

For issues:

1. Run test_connection.py to diagnose
2. Check Wazuh logs: tail -f /var/ossec/logs/ossec.log
3. Review Claude Desktop logs
4. Verify network connectivity between your machine and Wazuh manager

License

MIT

Changelog

v1.0.0 (2026-01-02)

• Initial release
• 4 core tools: critical_alerts, investigate_host, brute_force_detection, security_summary
• Full Wazuh API client
• Claude Desktop integration
• Comprehensive setup guide

---

Built for learning and security automation 🔍