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
-
Make sure you have Python 3.12+ installed.
-
Create a virtual environment (optional but recommended):
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate -
Install dependencies:
pip install -r requirements.txt -
Configure AWS credentials if you haven't already:
aws configureOr 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 integrationaws_cloudwatch.py- Simplified AWS CloudWatch integration moduletest_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 groupscloudwatch://log-groups/{log_group_name}- Gets detailed information about a specific log groupcloudwatch://alarms- Lists all CloudWatch alarmscloudwatch://alarms/in-alarm- Lists only CloudWatch alarms currently in ALARM statecloudwatch://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 queryquery_string: CloudWatch Insights query stringstart_time: (Optional) Start time for the query in Unix timestamp millisecondsend_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
- Parameters:
-
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)
- Parameters:
-
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
- Parameters:
-
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:
# 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