Retrieves security alerts from Elasticsearch indices containing Wazuh data, transforming them into standardized MCP messages.
Uses Flask to expose an HTTP endpoint for serving transformed security event data to clients.
Wazuh MCP Remote Server v4.0.3
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
๐ Features
Core Capabilities
๐ 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
๐ MCP 2025-06-18 Specification Compliance
This implementation 100% complies with the latest MCP specification:
Standard | Status | Implementation |
๐ Streamable HTTP | โ COMPLIANT |
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
endpoint maintained |
๐ Session Management | โ COMPLIANT | Full session lifecycle with DELETE support |
Perfect Score: 33/33 Requirements Met โญ
๐ View Full Compliance Verification โ
References:
Wazuh Integration
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
29 Specialized Tools
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
Related MCP server: OpenSearch MCP Server
๐ Quick Start
Prerequisites
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.
1. Clone Repository
2. Configure Environment
Essential Configuration:
3. Deploy with Docker (OS-Agnostic)
Option 1: Python Deployment Script (Recommended - Works on all platforms)
Option 2: Platform-Specific Scripts
4. Get Authentication Token
5. Verify MCP Endpoint
๐ Configuration
Environment Variables
Variable | Description | Default | Required |
| Wazuh server URL | - | โ |
| API username | - | โ |
| API password | - | โ |
| API port |
| โ |
| Wazuh Indexer hostname (required for vulnerability tools in 4.8.0+) | - | โ* |
| Wazuh Indexer port |
| โ |
| Wazuh Indexer username | - | โ* |
| Wazuh Indexer password | - | โ* |
| Server bind address |
| โ |
| Server port |
| โ |
| Authentication mode:
,
,
|
| โ |
| JWT signing key | auto-generated | โ |
| Enable OAuth Dynamic Client Registration |
| โ |
| Logging level |
| โ |
| SSL verification |
| โ |
| CORS origins |
| โ |
| Redis URL for serverless sessions | - | โ |
| Session TTL (Redis only) |
| โ |
Note: *
WAZUH_INDEXER_*variables are required for vulnerability tools when using Wazuh 4.8.0+. The/vulnerabilityAPI was removed in Wazuh 4.8.0.
Docker Compose Configuration
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
๐ง Development
Local Development Setup
Option 1: Docker Development Environment
Option 2: Native Python Development
Project Structure
Building Custom Images
๐ก๏ธ Security
Production Security Features
๐ 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
Security Best Practices
๐ Advanced Features
High Availability (HA)
The 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:
Serverless Ready
Enable horizontally scalable, serverless deployments with external session storage:
Default Mode: In-Memory Sessions
โ Zero configuration
โ Works immediately
โ Sessions lost on restart
โ Cannot scale horizontally
Serverless Mode: Redis Sessions
โ Sessions persist across restarts
โ Horizontal scaling support
โ Serverless compatible (AWS Lambda, Cloud Run)
โ Automatic session expiration
Redis Setup (Optional):
Verification:
๐ Monitoring & Operations
Health Monitoring
Log Management
Performance Monitoring
Prometheus Metrics:
/metricsendpointHealth Checks:
/healthwith detailed statusRequest Tracing: Structured JSON logging
Resource Usage: Docker stats integration
๐ง Management Commands
Docker Compose Operations
Maintenance
๐ API Reference
MCP Protocol Endpoints
Endpoint | Method | Description |
| GET/POST | Recommended MCP endpoint (Streamable HTTP - 2025-06-18) |
| GET | Legacy SSE endpoint (backward compatibility) |
| POST | JSON-RPC 2.0 endpoint (alternative API access) |
| GET | Health check and status |
| GET | Prometheus metrics |
| GET | OpenAPI documentation |
Authentication Endpoints
Endpoint | Method | Description |
| POST | Exchange API key for JWT token (bearer mode) |
| GET | OAuth 2.0 discovery (oauth mode) |
| GET | OAuth authorization endpoint |
| POST | OAuth token exchange |
| POST | Dynamic Client Registration (DCR) |
Claude Desktop: Use
/mcpendpoint with OAuth mode for best experience
Authentication
๐ค Integration
๐ค Claude Desktop Integration
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.
Prerequisites
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
Step 1: Deploy Your Server
Ensure your Wazuh MCP Server is running and publicly accessible:
Step 2: Add Custom Connector in Claude Desktop
Open Claude Desktop
Go to Settings โ Connectors
Click "Add custom connector"
Enter your MCP server URL:
Recommended (Streamable HTTP):
https://your-server-domain.com/mcpLegacy (SSE):
https://your-server-domain.com/sse
In Advanced settings, add your Bearer token for authentication
Click Connect
Step 3: Enable Tools in Chat
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
Authentication Modes
The server supports three authentication modes configured via AUTH_MODE environment variable:
Mode |
| Use Case | Claude Desktop Support |
OAuth |
| Production with Claude Desktop | โ Native (recommended) |
Bearer Token |
| API/Programmatic access | โ Via Advanced settings |
Authless |
| Development/Testing | โ Direct connect |
Option A: OAuth (Recommended for Claude Desktop)
OAuth with Dynamic Client Registration (DCR) provides the best Claude Desktop experience.
How it works:
Claude Desktop discovers OAuth endpoints via
/.well-known/oauth-authorization-serverAutomatically registers as a client (DCR)
Handles authorization flow seamlessly
OAuth Endpoints:
Discovery:
/.well-known/oauth-authorization-serverAuthorization:
/oauth/authorizeToken:
/oauth/tokenRegistration:
/oauth/register(DCR)
Option B: Bearer Token (Programmatic Access)
For API access or when OAuth is not available:
Step 1: Get API Key
Step 2: Exchange for JWT Token
Step 3: Use Bearer Token Add the token in Claude Desktop's Advanced settings or API requests.
Option C: Authless (Development Only)
For local development and testing only. Not recommended for production.
No authentication required - clients connect directly.
Supported Features
Feature | Status |
Tools | โ Supported |
Prompts | โ Supported |
Resources | โ Supported |
Text/Image Results | โ Supported |
Resource Subscriptions | โ Not yet supported |
Sampling | โ Not yet supported |
โ ๏ธ Common Mistake: Using JSON Config for Remote Servers
โ This will NOT work โ the JSON config is for local stdio servers only:
This produces the error:
โ 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)
Programmatic Access
Using the official /sse endpoint:
Using JSON-RPC endpoint (alternative):
๐จ Troubleshooting
Common Issues
MCP
Claude Desktop Connection Issues
Connection Refused
Authentication Errors
SSL/TLS Issues
Support Resources
๐ Documentation: MCP Specification
๐ Issues: Check your repository's issues section
๐ฌ Discussions: Repository discussions section
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Acknowledgments
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.
๐ค Contributors Wanted
๐งช Help Us Test & Improve
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.pyReport 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
๐ Production Features
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
๐ Thanks
A huge thank you to everyone who has contributed to this project through issues, pull requests, and discussions!
Contributors
Avatar | Username | Contributions |
๐ป Code, ๐ Issues, ๐ฌ Discussions | ||
๐ป Code, ๐ฌ Discussions | ||
๐ป Code, ๐ PRs | ||
๐ป Code, ๐ Issues, ๐ PRs | ||
๐ป Code, ๐ PRs | ||
๐ PRs | ||
๐ PRs | ||
๐ Issues | ||
๐ Issues | ||
๐ Issues | ||
๐ Issues | ||
๐ Issues | ||
๐ Issues | ||
๐ Issues | ||
๐ Issues | ||
๐ Issues | ||
๐ฌ Discussions | ||
๐ฌ Discussions | ||
๐ฌ Discussions |
Legend: ๐ป Code ยท ๐ Issues ยท ๐ Pull Requests ยท ๐ฌ Discussions
This section is automatically updated by GitHub Actions. See .github/workflows/update-contributors.yml
๐ Summary
The Wazuh MCP Remote Server represents a gold standard implementation of Anthropic's MCP remote server specifications:
โ What Makes This Special
๐ฏ 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
๐ Ready for Production
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.