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:

Or using the MCP CLI:

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:

Examples with MCP CLI

Using the MCP CLI:

License

MIT