MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

C
Cloudwatch MCP Server
by @shubhamgosain
GitHub Repo(1 stars)

MCP server by shubhamgosain

Created 12/30/2025
Updated about 3 hours ago
README
View Source
Repository documentation and setup instructions

CloudWatch MCP Server

A Model Context Protocol (MCP) server for AWS CloudWatch. Query metrics, list namespaces, describe alarms, and more directly from your AI assistant.

Features

  • Query Metrics: Get time-series metric data with configurable statistics and time ranges
  • List Namespaces: Discover all CloudWatch namespaces in your AWS account
  • List Metrics: Browse available metrics, optionally filtered by namespace
  • List Dimension Values: Get unique values for metric dimensions (e.g., all EC2 instance IDs)
  • Describe Alarms: View CloudWatch alarms with filtering by state or name
  • Health Check: Verify AWS connectivity

Prerequisites

  • Node.js: Version 18.0.0 or higher
  • AWS Account: With CloudWatch access
  • AWS Credentials: Configured via IAM role, environment variables, or credentials file

Quick Start

# 1. Clone and install
git clone https://github.com/your-org/cloudwatch-mcp-server.git
cd cloudwatch-mcp-server
npm install

# 2. Configure AWS credentials (if not using IAM role)
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

# 3. Run the server
npm start

Installation

# Clone the repository
git clone https://github.com/your-org/cloudwatch-mcp-server.git
cd cloudwatch-mcp-server

# Install dependencies
npm install

# Build (automatically runs during npm install)
npm run build

Authentication

The server uses the AWS default credential chain (in order of precedence):

  1. Environment Variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  2. Shared Credentials File: ~/.aws/credentials
  3. IAM Role (recommended for EC2, ECS, Lambda, EKS)
  4. AWS SSO: Via aws sso login

Required IAM Permissions

Ensure your credentials have CloudWatch read permissions. Minimal IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics",
        "cloudwatch:DescribeAlarms"
      ],
      "Resource": "*"
    }
  ]
}

Usage

With Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cloudwatch": {
      "command": "node",
      "args": ["/absolute/path/to/cloudwatch-mcp-server/dist/index.js"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key"
      }
    }
  }
}

Note: Replace /absolute/path/to/ with the actual path where you cloned the repository. You can omit the AWS credential env vars if using IAM roles or credentials file.

With Cursor

Add to your Cursor MCP settings (Settings → MCP → Edit Config):

{
  "mcpServers": {
    "cloudwatch": {
      "command": "node",
      "args": ["/absolute/path/to/cloudwatch-mcp-server/dist/index.js"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Standalone (HTTP Transport)

# Run with HTTP transport
npm start -- --transport http --port 8080

# Or using environment variables
MCP_TRANSPORT=http MCP_PORT=8080 npm start

Development

# Run in development mode (with hot reload via tsx)
npm run dev

# Run with HTTP transport in development
npm run dev -- --transport http --port 8080

Available Tools

aws_cloudwatch_health_check

Test connectivity to AWS CloudWatch.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | region | string | No | AWS region to check |

aws_cloudwatch_query_metric

Query CloudWatch metric data. Returns time series data for a specific metric.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | namespace | string | Yes | - | CloudWatch namespace (e.g., 'AWS/EC2') | | metricName | string | Yes | - | Name of the metric (e.g., 'CPUUtilization') | | dimensions | object | No | - | Key-value pairs for dimensions | | statistic | string | No | Average | Average, Sum, Minimum, Maximum, SampleCount | | period | number | No | 300 | Period in seconds | | startTime | string | No | now-1h | Start time (ISO 8601 or relative like 'now-1h') | | endTime | string | No | now | End time (ISO 8601 or 'now') | | region | string | No | - | AWS region |

Example prompt:

"Query the average CPU utilization for EC2 instance i-1234567890abcdef0 over the last 2 hours"

aws_cloudwatch_list_namespaces

List all available CloudWatch namespaces in your AWS account.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | region | string | No | AWS region |

aws_cloudwatch_list_metrics

List CloudWatch metrics with optional filtering.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | namespace | string | No | Filter by namespace | | metricName | string | No | Filter by metric name | | region | string | No | AWS region |

aws_cloudwatch_list_dimension_values

Get unique values for a metric dimension. Useful for discovering available resources.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | namespace | string | Yes | CloudWatch namespace | | metricName | string | Yes | Metric name | | dimensionName | string | Yes | Dimension to get values for | | region | string | No | AWS region |

Example prompt:

"List all EC2 instance IDs that have CPUUtilization metrics"

aws_cloudwatch_describe_alarms

Describe CloudWatch alarms with optional filtering.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | alarmNames | string[] | No | Specific alarm names to describe | | alarmNamePrefix | string | No | Filter by name prefix | | stateValue | string | No | Filter by state: OK, ALARM, INSUFFICIENT_DATA | | region | string | No | AWS region |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | AWS_REGION | AWS region for CloudWatch | us-east-1 | | AWS_DEFAULT_REGION | Alternative region variable | us-east-1 | | AWS_ACCESS_KEY_ID | AWS access key | - | | AWS_SECRET_ACCESS_KEY | AWS secret key | - | | AWS_PROFILE | AWS credentials profile name | default | | LOG_LEVEL | Logging level (debug, info, warn, error) | info | | MCP_TRANSPORT | Transport type (stdio, http) | stdio | | MCP_PORT | Port for HTTP transport | 8080 |

Common CloudWatch Namespaces

| Namespace | Service | |-----------|---------| | AWS/EC2 | EC2 instances | | AWS/ECS | Elastic Container Service | | AWS/EKS | Elastic Kubernetes Service | | AWS/Lambda | Lambda functions | | AWS/RDS | Relational Database Service | | AWS/DynamoDB | DynamoDB tables | | AWS/S3 | S3 buckets | | AWS/ELB | Classic Load Balancer | | AWS/ApplicationELB | Application Load Balancer | | AWS/NetworkELB | Network Load Balancer | | AWS/ApiGateway | API Gateway | | AWS/SQS | Simple Queue Service | | AWS/SNS | Simple Notification Service | | AWS/Kinesis | Kinesis streams | | AWS/CloudFront | CloudFront distributions |

Example Prompts

Once connected to your AI assistant, try these prompts:

  • "What CloudWatch namespaces are available in my AWS account?"
  • "Show me the CPU utilization for my EC2 instances over the last hour"
  • "List all CloudWatch alarms that are currently in ALARM state"
  • "What metrics are available for Lambda functions?"
  • "Get the average response time for my Application Load Balancer"
  • "List all EC2 instance IDs that have metrics"
  • "Show me memory utilization for RDS database 'production-db' over the last 24 hours"

Troubleshooting

"Could not load credentials"

AWS credentials are not configured. Options:

  1. Set environment variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  2. Configure ~/.aws/credentials file
  3. Run aws configure to set up credentials
  4. Use IAM role (for EC2/ECS/Lambda)

"Access Denied" errors

Your IAM user/role lacks required permissions. Ensure you have:

  • cloudwatch:GetMetricData
  • cloudwatch:ListMetrics
  • cloudwatch:DescribeAlarms

"No metrics found"

  • Verify the namespace spelling (case-sensitive)
  • Ensure resources exist in the specified region
  • Some metrics only appear after resources are active

Server not starting

  1. Check Node.js version: node --version (must be ≥18.0.0)
  2. Rebuild: npm run clean && npm install
  3. Check logs: Set LOG_LEVEL=debug for verbose output

Claude Desktop / Cursor not connecting

  1. Verify the path in config is absolute (not relative)
  2. Ensure the server was built: npm run build
  3. Test manually: node /path/to/dist/index.js --help
  4. Restart Claude Desktop / Cursor after config changes

Testing

The project includes a comprehensive test suite using Jest.

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test Structure

tests/
├── lib/
│   └── logging.test.ts          # Logging module tests
└── tools/
    └── cloudwatch/
        ├── client.test.ts       # AWS SDK client tests (mocked)
        ├── schema.test.ts       # Zod schema validation tests
        └── tools.test.ts        # MCP tool structure tests

Test Coverage

| Module | Coverage | |--------|----------| | lib/logging.ts | 100% | | tools/cloudwatch/schema.ts | 100% | | tools/cloudwatch/client.ts | ~86% | | tools/cloudwatch/tools.ts | ~14% (structure only) |

The client tests mock the AWS SDK to test business logic without real AWS calls. Tool tests focus on validating structure and parameter schemas.

Project Structure

cloudwatch-mcp-server/
├── src/
│   ├── index.ts                 # Main MCP server entry point
│   ├── lib/
│   │   └── logging.ts           # Winston-based JSON logging
│   └── tools/
│       └── cloudwatch/
│           ├── client.ts        # AWS SDK CloudWatch client
│           ├── schema.ts        # Zod schemas for validation
│           ├── tools.ts         # MCP tool definitions
│           └── index.ts         # Exports
├── tests/                       # Unit tests
│   ├── lib/
│   └── tools/cloudwatch/
├── dist/                        # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── jest.config.js               # Jest configuration
└── README.md

License

MIT

Quick Setup
Installation guide for this server

Install Package (if required)

npx @modelcontextprotocol/server-cloudwatch-mcp-server

Cursor configuration (mcp.json)

{ "mcpServers": { "shubhamgosain-cloudwatch-mcp-server": { "command": "npx", "args": [ "shubhamgosain-cloudwatch-mcp-server" ] } } }