A production-ready, enterprise-grade MCP-compliant remote server that provides seamless integration with Wazuh SIEM platform using the latest Streamable HTTP transport (MCP 2025-06-18).
Latest Standard: Streamable HTTP transport with
/mcpendpoint (2025-06-18)Backwards Compatible: Legacy
/sseendpoint maintainedCompliance: β 100% compliant with MCP 2025-06-18 specification
- π MCP-Compliant Remote Server: Full compliance with MCP 2025-06-18 specification
- β‘ Streamable HTTP Transport: Modern
/mcpendpoint with dynamic SSE upgrade - π Backwards Compatible: Legacy
/sseendpoint for older clients - π‘ Protocol Versioning: Supports 2025-06-18, 2025-03-26, and 2024-11-05
- π Bearer Token Authentication: JWT-based authentication for secure remote access
- π‘οΈ Production Security: Rate limiting, input validation, CORS protection, origin validation
- π Comprehensive Monitoring: Prometheus metrics, health checks, structured logging
- π³ 100% Containerized: Everything in Docker - OS-agnostic deployment (Windows/macOS/Linux)
- π Zero Host Dependencies: No Python, tools, or libraries needed on host system
- π High Availability: Integrated circuit breakers, exponential backoff retry logic, graceful shutdown with connection draining
- βοΈ Serverless Ready: Pluggable session storage (Redis or in-memory), stateless operations, horizontal scaling support
This implementation 100% complies with the latest MCP specification:
| Standard | Status | Implementation |
|---|---|---|
| π Streamable HTTP | β COMPLIANT | /mcp endpoint with POST/GET/DELETE support |
| π‘ Protocol Versioning | β COMPLIANT | MCP-Protocol-Version header validation |
| β‘ Dynamic Streaming | β COMPLIANT | JSON or SSE based on Accept header |
| π Authentication | β COMPLIANT | Bearer token (JWT) authentication |
| π‘οΈ Security | β COMPLIANT | HTTPS, origin validation, rate limiting |
| π Legacy Support | β COMPLIANT | Legacy /sse endpoint maintained |
| π Session Management | β COMPLIANT | Full session lifecycle with DELETE support |
Perfect Score: 33/33 Requirements Met β
π View Full Compliance Verification β
References:
Supported Wazuh Versions: 4.8.0 - 4.14.1 β
- π Advanced Security Monitoring: Real-time alert analysis and threat detection
- π₯ Agent Management: Comprehensive agent lifecycle and health monitoring
- π¨ Incident Response: Automated threat hunting and response capabilities
- π Security Analytics: Performance metrics and compliance reporting
- π Multi-Environment: Support for cloud, on-premise, and hybrid deployments
- π Latest Features: Full support for Wazuh 4.14.1 enhancements including improved vulnerability scanning and AWS integrations
Comprehensive toolkit for security operations including:
Alert Management (4 tools)
- get_wazuh_alerts: Retrieve security alerts with filtering
- get_wazuh_alert_summary: Alert summaries grouped by field
- analyze_alert_patterns: Pattern analysis and anomaly detection
- search_security_events: Advanced security event search
Agent Management (6 tools)
- get_wazuh_agents: Agent information and status
- get_wazuh_running_agents: Active agent monitoring
- check_agent_health: Agent health status checks
- get_agent_processes: Running process inventory
- get_agent_ports: Open port monitoring
- get_agent_configuration: Agent configuration details
Vulnerability Management (3 tools)
- get_wazuh_vulnerabilities: Vulnerability assessments
- get_wazuh_critical_vulnerabilities: Critical vulnerability focus
- get_wazuh_vulnerability_summary: Vulnerability statistics
Security Analysis (6 tools)
- analyze_security_threat: AI-powered threat analysis
- check_ioc_reputation: IoC reputation checking
- perform_risk_assessment: Comprehensive risk analysis
- get_top_security_threats: Top threat identification
- generate_security_report: Automated security reporting
- run_compliance_check: Framework compliance validation
System Monitoring (10 tools)
- get_wazuh_statistics: Comprehensive system metrics
- get_wazuh_weekly_stats: Weekly trend analysis
- get_wazuh_cluster_health: Cluster health monitoring
- get_wazuh_cluster_nodes: Node status and information
- get_wazuh_rules_summary: Rule effectiveness analysis
- get_wazuh_remoted_stats: Agent communication statistics
- get_wazuh_log_collector_stats: Log collection metrics
- search_wazuh_manager_logs: Manager log search
- get_wazuh_manager_error_logs: Error log analysis
- validate_wazuh_connection: Connection validation
- Docker 20.10+ with Compose v2.20+
- Python 3.9+ (optional, for OS-agnostic deployment script)
- Wazuh 4.8.0 - 4.14.1 deployment with API access
OS-Agnostic Deployment: Everything runs in Docker containers. Works on Windows, macOS, and Linux identically.
git clone <your-repository-url>
cd Wazuh-MCP-Server# Copy environment template
cp .env.example .env
# Edit configuration (required)
# Windows: notepad .env
# macOS/Linux: nano .envEssential Configuration:
# Wazuh Server Connection
WAZUH_HOST=https://your-wazuh-server.com
WAZUH_USER=your-api-user
WAZUH_PASS=your-api-password
WAZUH_PORT=55000
# MCP Remote Server Configuration
MCP_HOST=0.0.0.0
MCP_PORT=3000
# Authentication (JWT Secret Key)
AUTH_SECRET_KEY=your-secret-key-here
# CORS for Claude Desktop
ALLOWED_ORIGINS=https://claude.ai,https://*.anthropic.comOption 1: Python Deployment Script (Recommended - Works on all platforms)
# Windows
python deploy.py
# macOS/Linux
python3 deploy.pyOption 2: Platform-Specific Scripts
# Linux/macOS
./deploy-production.sh
# Windows (PowerShell/CMD)
deploy.bat
# Or use Docker Compose directly (all platforms)
docker compose up -d --wait# Server will generate an API key on startup (check logs)
docker compose logs wazuh-mcp-remote-server | grep "API key"
# Exchange API key for JWT token
curl -X POST http://localhost:3000/auth/token \
-H "Content-Type: application/json" \
-d '{"api_key": "wazuh_your-generated-api-key"}'# Test the official /sse endpoint
curl -H "Authorization: Bearer your-jwt-token" \
-H "Origin: http://localhost" \
-H "Accept: text/event-stream" \
http://localhost:3000/sse
# Check service status
docker compose ps
# Health check
curl http://localhost:3000/health| Variable | Description | Default | Required |
|---|---|---|---|
WAZUH_HOST |
Wazuh server URL | - | β |
WAZUH_USER |
API username | - | β |
WAZUH_PASS |
API password | - | β |
WAZUH_PORT |
API port | 55000 |
β |
MCP_HOST |
Server bind address | 0.0.0.0 |
β |
MCP_PORT |
Server port | 3000 |
β |
AUTH_MODE |
Authentication mode: oauth, bearer, none |
bearer |
β |
AUTH_SECRET_KEY |
JWT signing key | auto-generated | β |
OAUTH_ENABLE_DCR |
Enable OAuth Dynamic Client Registration | true |
β |
LOG_LEVEL |
Logging level | INFO |
β |
WAZUH_VERIFY_SSL |
SSL verification | false |
β |
ALLOWED_ORIGINS |
CORS origins | https://claude.ai |
β |
REDIS_URL |
Redis URL for serverless sessions | - | β |
SESSION_TTL_SECONDS |
Session TTL (Redis only) | 1800 |
β |
The compose.yml follows Docker Compose v2 latest naming convention and includes:
- Multi-platform builds (AMD64/ARM64)
- Security hardening (non-root user, read-only filesystem)
- Resource limits (CPU/Memory constraints)
- Health checks with automatic recovery
- Structured logging with rotation
Option 1: Docker Development Environment
# Run with development compose file
docker compose -f compose.dev.yml up -d --build
# View logs
docker compose -f compose.dev.yml logs -fOption 2: Native Python Development
# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Run development server
python -m wazuh_mcp_serversrc/wazuh_mcp_server/
βββ __main__.py # Application entry point
βββ server.py # MCP-compliant FastAPI server
βββ config.py # Configuration management
βββ auth.py # Authentication & authorization
βββ security.py # Security middleware & validation
βββ monitoring.py # Metrics & health checks
βββ resilience.py # Circuit breakers & retry logic
βββ api/
β βββ wazuh_client.py # Wazuh API client
βββ tools/ # MCP tools implementation
βββ core.py # 3 essential security tools
# Build for current platform
docker build -t wazuh-mcp-server:custom .
# Multi-platform build
docker buildx build --platform linux/amd64,linux/arm64 -t wazuh-mcp-server:multi .- π Authentication: JWT-based API key authentication
- π« Rate Limiting: Per-client request throttling
- π‘οΈ Input Validation: SQL injection and XSS protection
- π CORS Protection: Configurable origin restrictions
- π TLS Support: HTTPS/WSS encryption ready
- π€ Non-root Execution: Container security hardening
# Generate secure API key
openssl rand -hex 32
# Set restrictive file permissions
chmod 600 .env
chmod 700 deploy-production.sh
# Regular security updates
docker compose pull
docker compose up -dThe server includes production-grade HA features for maximum reliability:
Circuit Breakers
- Automatically opens after 5 consecutive failures
- Prevents cascading failures to Wazuh API
- Recovers automatically after 60 seconds
- Falls back gracefully during outages
Retry Logic
- Exponential backoff with jitter
- 3 retry attempts with 1-10 second delays
- Applies to all Wazuh API calls
- Handles transient network failures
Graceful Shutdown
- Waits for active connections to complete (max 30s)
- Runs cleanup tasks before termination
- Prevents data loss during restarts
- Integrates with Docker health checks
Implementation:
# Automatically applied to all Wazuh API calls
# No configuration required - works out of the boxEnable horizontally scalable, serverless deployments with external session storage:
Default Mode: In-Memory Sessions
# Single-instance deployments (default)
# No configuration needed
docker compose up -d- β Zero configuration
- β Works immediately
- β Sessions lost on restart
- β Cannot scale horizontally
Serverless Mode: Redis Sessions
# Multi-instance/serverless deployments
# Configure Redis in .env file
REDIS_URL=redis://redis:6379/0
SESSION_TTL_SECONDS=1800 # 30 minutes
# Deploy with Redis
docker compose -f compose.yml -f compose.redis.yml up -d- β Sessions persist across restarts
- β Horizontal scaling support
- β Serverless compatible (AWS Lambda, Cloud Run)
- β Automatic session expiration
Redis Setup (Optional):
# compose.redis.yml
services:
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
- redis-data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
volumes:
redis-data:Verification:
# Check session storage mode
curl http://localhost:3000/health | jq '.session_storage'
# Output:
# {
# "type": "InMemorySessionStore" # or "RedisSessionStore"
# "sessions_count": 5
# }# Application health
curl http://localhost:3000/health
# Detailed metrics
curl http://localhost:3000/metrics
# Container health
docker inspect wazuh-mcp-server --format='{{.State.Health.Status}}'# Follow live logs
docker compose logs -f --timestamps wazuh-mcp-server
# Export logs
docker compose logs --since=24h wazuh-mcp-server > server.log- Prometheus Metrics:
/metricsendpoint - Health Checks:
/healthwith detailed status - Request Tracing: Structured JSON logging
- Resource Usage: Docker stats integration
# Deploy/Update
./deploy-production.sh
# View status
docker compose ps --format table
# Scale service
docker compose up --scale wazuh-mcp-server=2 -d
# Stop services
docker compose down --timeout 30
# Full cleanup
docker compose down --volumes --remove-orphans# Update images
docker compose pull && docker compose up -d
# Backup configuration
tar -czf backup-$(date +%Y%m%d).tar.gz .env compose.yml
# View resource usage
docker stats wazuh-mcp-server --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"| Endpoint | Method | Description |
|---|---|---|
/mcp |
GET/POST | Recommended MCP endpoint (Streamable HTTP - 2025-06-18) |
/sse |
GET | Legacy SSE endpoint (backward compatibility) |
/ |
POST | JSON-RPC 2.0 endpoint (alternative API access) |
/health |
GET | Health check and status |
/metrics |
GET | Prometheus metrics |
/docs |
GET | OpenAPI documentation |
| Endpoint | Method | Description |
|---|---|---|
/auth/token |
POST | Exchange API key for JWT token (bearer mode) |
/.well-known/oauth-authorization-server |
GET | OAuth 2.0 discovery (oauth mode) |
/oauth/authorize |
GET | OAuth authorization endpoint |
/oauth/token |
POST | OAuth token exchange |
/oauth/register |
POST | Dynamic Client Registration (DCR) |
Claude Desktop: Use
/mcpendpoint with OAuth mode for best experience
# Get access token
curl -X POST http://localhost:3000/auth/token \
-H "Content-Type: application/json" \
-d '{"api_key": "your-api-key"}'
# Use token in requests
curl -H "Authorization: Bearer <token>" http://localhost:3000/Important: Claude Desktop supports remote MCP servers through the Connectors UI, not via the
claude_desktop_config.jsonfile. The JSON config file only supports local stdio-based MCP servers.
- Claude Pro, Max, Team, or Enterprise plan (required for custom connectors)
- Your Wazuh MCP Server deployed and accessible via HTTPS
- Custom Connectors feature is currently in beta
Ensure your Wazuh MCP Server is running and publicly accessible:
# Deploy the server
docker compose up -d
# Verify it's running (must be HTTPS in production)
curl https://your-server-domain.com/health- Open Claude Desktop
- Go to Settings β Connectors
- Click "Add custom connector"
- Enter your MCP server URL:
- Recommended (Streamable HTTP):
https://your-server-domain.com/mcp - Legacy (SSE):
https://your-server-domain.com/sse
- Recommended (Streamable HTTP):
- In Advanced settings, add your Bearer token for authentication
- Click Connect
- In your chat interface, click the "Search and tools" button
- Find your Wazuh connector in the list
- Click "Connect" to authenticate (if required)
- Enable/disable specific tools as needed
The server supports three authentication modes configured via AUTH_MODE environment variable:
| Mode | AUTH_MODE |
Use Case | Claude Desktop Support |
|---|---|---|---|
| OAuth | oauth |
Production with Claude Desktop | β Native (recommended) |
| Bearer Token | bearer |
API/Programmatic access | β Via Advanced settings |
| Authless | none |
Development/Testing | β Direct connect |
OAuth with Dynamic Client Registration (DCR) provides the best Claude Desktop experience.
# Set environment variable
AUTH_MODE=oauth docker compose up -dHow it works:
- Claude Desktop discovers OAuth endpoints via
/.well-known/oauth-authorization-server - Automatically registers as a client (DCR)
- Handles authorization flow seamlessly
OAuth Endpoints:
- Discovery:
/.well-known/oauth-authorization-server - Authorization:
/oauth/authorize - Token:
/oauth/token - Registration:
/oauth/register(DCR)
For API access or when OAuth is not available:
# Default mode
AUTH_MODE=bearer docker compose up -dStep 1: Get API Key
docker compose logs wazuh-mcp-remote-server | grep "API key"Step 2: Exchange for JWT Token
curl -X POST https://your-server-domain.com/auth/token \
-H "Content-Type: application/json" \
-d '{"api_key": "wazuh_your-generated-api-key"}'Step 3: Use Bearer Token Add the token in Claude Desktop's Advanced settings or API requests.
For local development and testing only. Not recommended for production.
AUTH_MODE=none docker compose up -dNo authentication required - clients connect directly.
| Feature | Status |
|---|---|
| Tools | β Supported |
| Prompts | β Supported |
| Resources | β Supported |
| Text/Image Results | β Supported |
| Resource Subscriptions | β Not yet supported |
| Sampling | β Not yet supported |
β This will NOT work β the JSON config is for local stdio servers only:
{
"mcpServers": {
"wazuh-security": {
"url": "https://your-server.com/mcp",
"headers": { "Authorization": "Bearer ..." }
}
}
}This produces the error:
Could not load app settings
"path": ["mcpServers", "wazuh-security", "command"]
"message": "Required"
β Correct approach: Use Settings β Connectors UI as described above.
Requirements Checklist:
- β Claude Pro, Max, Team, or Enterprise plan
- β Use Connectors UI (Settings β Connectors), NOT
claude_desktop_config.json- β Server must be accessible via HTTPS (production)
- β Use
/mcpendpoint (Streamable HTTP) or/sseendpoint (legacy)- β Authentication: OAuth (recommended), Bearer token, or Authless (dev only)
Using the official /sse endpoint:
import httpx
import asyncio
async def connect_to_mcp_sse():
"""Connect to MCP server using SSE endpoint."""
async with httpx.AsyncClient() as client:
# Get authentication token first
auth_response = await client.post(
"http://localhost:3000/auth/token",
json={"api_key": "your-api-key"}
)
token = auth_response.json()["access_token"]
# Connect to SSE endpoint
async with client.stream(
"GET",
"http://localhost:3000/sse",
headers={
"Authorization": f"Bearer {token}",
"Accept": "text/event-stream",
"Origin": "http://localhost"
}
) as response:
async for chunk in response.aiter_text():
print(f"Received: {chunk}")
# Run the SSE client
asyncio.run(connect_to_mcp_sse())Using JSON-RPC endpoint (alternative):
import httpx
async def query_wazuh_mcp():
async with httpx.AsyncClient() as client:
# Get authentication token
auth_response = await client.post(
"http://localhost:3000/auth/token",
json={"api_key": "your-api-key"}
)
token = auth_response.json()["access_token"]
# Make JSON-RPC request
response = await client.post(
"http://localhost:3000/",
headers={
"Authorization": f"Bearer {token}",
"Origin": "http://localhost"
},
json={
"jsonrpc": "2.0",
"id": "1",
"method": "tools/list"
}
)
return response.json()MCP /sse Endpoint Issues
# Test SSE endpoint authentication
curl -I http://localhost:3000/sse
# Expected: 401 Unauthorized (good - auth required)
# Test with valid token
curl -H "Authorization: Bearer your-jwt-token" \
-H "Origin: http://localhost" \
-H "Accept: text/event-stream" \
http://localhost:3000/sse
# Expected: 200 OK with SSE stream
# Get new authentication token
curl -X POST http://localhost:3000/auth/token \
-H "Content-Type: application/json" \
-d '{"api_key": "your-api-key"}'Claude Desktop Connection Issues
# Verify Claude Desktop can reach the server
curl http://localhost:3000/health
# Expected: {"status": "healthy"}
# Check CORS configuration
grep ALLOWED_ORIGINS .env
# Should include: https://claude.ai,https://*.anthropic.comConnection Refused
# Check service status
docker compose ps
docker compose logs wazuh-mcp-remote-server
# Verify port availability
netstat -ln | grep 3000Authentication Errors
# Verify Wazuh credentials
curl -u "$WAZUH_USER:$WAZUH_PASS" "$WAZUH_HOST:$WAZUH_PORT/"
# Check API key in server logs
docker compose logs wazuh-mcp-remote-server | grep "API key"SSL/TLS Issues
# Disable SSL verification for testing
echo "WAZUH_VERIFY_SSL=false" >> .env
docker compose up -d- π Documentation: MCP Specification
- π Issues: Check your repository's issues section
- π¬ Discussions: Repository discussions section
This project is licensed under the MIT License - see the LICENSE file for details.
- Wazuh - Open source security platform
- Model Context Protocol - AI assistant integration standard
- FastAPI - Modern Python web framework
- Docker - Containerization platform
Built for the security community with production-ready MCP compliance.
We're looking for hands-on testers to deploy this MCP server in real-world environments and provide feedback!
What We Need:
- Deploy the server step-by-step following the documentation
- Test with actual Wazuh installations (v4.8.0 - v4.14.1)
- Try different deployment scenarios:
- Single-instance (in-memory sessions)
- Multi-instance with Redis (serverless mode)
- Various OS platforms (Linux/macOS/Windows)
- Different Wazuh configurations
How to Contribute:
-
Deploy & Test
# Follow the Quick Start guide git clone https://github.com/gensecaihq/Wazuh-MCP-Server.git cd Wazuh-MCP-Server python deploy.py
-
Report Findings
- Open an Issue for bugs or problems
- Share successful deployment stories
- Suggest improvements or missing features
- Report compatibility issues
-
What to Report
- Deployment environment (OS, Docker version, Wazuh version)
- Steps followed
- What worked / what didn't
- Error messages or logs
- Performance observations
- Integration results with Claude Desktop
We Value:
- Detailed bug reports with reproduction steps
- Real-world use case feedback
- Performance benchmarks
- Security findings
- Documentation improvements
- Integration testing results
Recognition: All contributors who provide valuable feedback will be acknowledged in the project!
π§ Questions? Open a Discussion or file an Issue
This production-ready remote MCP server implementation includes:
- β Full MCP protocol compliance (2025-06-18 specification)
- β 29 specialized security tools
- β Production-grade security hardening
- β Enterprise deployment readiness
- β Comprehensive monitoring and observability
A huge thank you to everyone who has contributed to this project through issues, pull requests, and discussions!
| Avatar | Username | Contributions |
|---|---|---|
| @alokemajumder | π» Code, π Issues, π¬ Discussions | |
| @gensecai-dev | π» Code, π¬ Discussions | |
| @aiunmukto | π» Code, π PRs | |
| @Karibusan | π» Code, π Issues, π PRs | |
| @lwsinclair | π» Code, π PRs | |
| @taylorwalton | π PRs | |
| @MilkyWay88 | π PRs | |
| @Uberkarhu | π Issues | |
| @cbassonbgroup | π Issues | |
| @cybersentinel-06 | π Issues | |
| @daod-arshad | π Issues | |
| @mamema | π Issues | |
| @marcolinux46 | π Issues | |
| @matveevandrey | π Issues | |
| @punkpeye | π Issues | |
| @tonyliu9189 | π Issues | |
| @Vasanth120v | π¬ Discussions | |
| @gnix45 | π¬ Discussions | |
| @melmasry1987 | π¬ Discussions |
Legend: π» Code Β· π Issues Β· π Pull Requests Β· π¬ Discussions
This section is automatically updated by GitHub Actions. See .github/workflows/update-contributors.yml
The Wazuh MCP Remote Server represents a gold standard implementation of Anthropic's MCP remote server specifications:
π― 100% MCP Compliant - Perfect compliance score (33/33 requirements)
β‘ Streamable HTTP & Legacy SSE - Latest /mcp endpoint plus backward-compatible /sse
π Enterprise Security - JWT authentication, rate limiting, CORS protection
π‘οΈ Production Ready - Docker containerized, multi-platform, health monitoring
π§ 29 Security Tools - Comprehensive Wazuh SIEM integration
π Observable - Prometheus metrics, structured logging, health checks
This implementation is immediately deployable in production environments and provides:
- β Seamless Claude Desktop integration
- β Enterprise-grade security and reliability
- β Scalable container-native architecture
- β Comprehensive monitoring and observability
- β Full compliance with MCP protocol standards
The result is a robust, secure, and highly capable MCP remote server that sets the standard for enterprise AI-SIEM integrations.