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 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:

# 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

AWS CloudWatch