CloudWatch MCP Server

# CloudWatch MCP Server This simplified MCP server provides a streamlined way to interact with AWS CloudWatch resources through the MCP protocol. It exposes CloudWatch log groups, log queries, and alarms as resources and tools. ## Features - List all CloudWatch log groups with their metadata - List all CloudWatch alarms with their current states - Query CloudWatch logs using CloudWatch Insights across multiple log groups - Discover available fields across multiple log groups with shared schema - Automatic JSON parsing for @message field in log queries - Check if specific log groups exist - Get detailed information about specific log groups - Filter alarms by state (all alarms or only those in ALARM state) - Retrieve all saved CloudWatch Logs Insights queries ## Prerequisites - Python 3.12 or higher - AWS credentials configured (via environment variables, AWS CLI, or IAM role) - MCP CLI (version 0.1.1 or higher) - Boto3 (AWS SDK for Python) ## Setup 1. Make sure you have Python 3.12+ installed. 2. Create a virtual environment (optional but recommended): ``` python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate ``` 3. Install dependencies: ``` pip install -r requirements.txt ``` 4. Configure AWS credentials if you haven't already: ``` aws configure ``` Or set environment variables: ``` export AWS_ACCESS_KEY_ID="your-access-key" export AWS_SECRET_ACCESS_KEY="your-secret-key" export AWS_REGION="your-region" ``` ## Project Structure - `cloudwatch_server.py` - MCP server implementation for CloudWatch integration - `aws_cloudwatch.py` - Simplified AWS CloudWatch integration module - `test_cloudwatch.py` - Command-line utility to test the CloudWatch integration ## Running the server Start the MCP server: ``` python cloudwatch_server.py ``` Or using the MCP CLI: ``` mcp run cloudwatch_server.py ``` ## Using the MCP server ### Resources The server exposes the following resources: - `cloudwatch://log-groups` - Lists all CloudWatch log groups - `cloudwatch://log-groups/{log_group_name}` - Gets detailed information about a specific log group - `cloudwatch://alarms` - Lists all CloudWatch alarms - `cloudwatch://alarms/in-alarm` - Lists only CloudWatch alarms currently in ALARM state - `cloudwatch://saved-queries` - Lists all saved CloudWatch Logs Insights queries ### Tools The server provides the following tools: - `query_logs` - Query CloudWatch logs using CloudWatch Insights - Parameters: - `log_group_names`: Single log group name or list of log group names to query - `query_string`: CloudWatch Insights query string - `start_time`: (Optional) Start time for the query in Unix timestamp milliseconds - `end_time`: (Optional) End time for the query in Unix timestamp milliseconds - Features: - Automatically parses JSON in @message field - Returns structured data for JSON messages - Handles multiple log groups in a single query - `discover_log_fields` - Discover available fields across multiple log groups - Parameters: - `log_group_names`: Single log group name or list of log group names to analyze - Features: - Efficiently discovers fields across multiple log groups - Assumes shared schema across log groups - Detects nested JSON fields in @message - Identifies field types (number, boolean, string, array) - `log_group_exists` - Check if CloudWatch log groups exist - Parameters: - `log_group_names`: Single log group name or list of log group names to check - Returns: - Dictionary mapping each log group to its existence status - `get_saved_queries` - Fetch all saved CloudWatch Logs Insights queries - No parameters required ## Testing the CloudWatch integration You can test the CloudWatch integration directly using the provided test script: ``` # Make the test file executable chmod +x test_cloudwatch.py # List all log groups ./test_cloudwatch.py log-groups # List all alarms ./test_cloudwatch.py alarms # Use a specific AWS profile ./test_cloudwatch.py log-groups --profile my-profile # Enable verbose logging ./test_cloudwatch.py alarms -v ``` ## Examples with MCP CLI Using the MCP CLI: ```bash # List all log groups mcp inspect cloudwatch://log-groups # Get details about a specific log group mcp inspect cloudwatch://log-groups/my-log-group-name # List all alarms mcp inspect cloudwatch://alarms # List alarms currently in ALARM state mcp inspect cloudwatch://alarms/in-alarm # List all saved CloudWatch Logs Insights queries mcp inspect cloudwatch://saved-queries # Query logs from multiple log groups using CloudWatch Insights mcp call query_logs --log_group_names '["log-group-1", "log-group-2"]' --query_string "fields @timestamp, @message | limit 10" # Query logs from a single log group (still supported) mcp call query_logs --log_group_names "my-log-group" --query_string "fields @timestamp, @message | limit 10" # Discover fields across multiple log groups mcp call discover_log_fields --log_group_names '["log-group-1", "log-group-2"]' # Check if multiple log groups exist mcp call log_group_exists --log_group_names '["log-group-1", "log-group-2"]' # Get all saved CloudWatch Logs Insights queries mcp call get_saved_queries ``` ## License MIT