Amazon CloudWatch Logs MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Amazon CloudWatch Logs services. This server enables AI assistants to manage CloudWatch logs through a standardized interface using AWS SDK.

Note: This project is currently under active development and not yet ready for production use. Features and APIs may change significantly before the first stable release.

Overview

This MCP server allows AI assistants to interact with Amazon CloudWatch Logs through the Model Context Protocol. It provides a standardized interface for performing various CloudWatch Logs operations, enabling comprehensive management and monitoring of log data.

Quick Start

Prerequisites

• AWS account with CloudWatch Logs access
• AWS access key and secret key with appropriate permissions
• Node.js (for npm installation) or Docker

Installation

Choose one of the following installation methods:

Option 1: npm Package

# Install the package
npm install -g @hyorimitsu/amazon-cloudwatch-logs-mcp-server

# Configure in your AI assistant's configuration
# See Configuration section below

Option 2: Docker Image

# Pull the Docker image
docker pull ghcr.io/hyorimitsu/mcp-amazon-cloudwatch-logs:latest

# Configure in your AI assistant's configuration
# See Configuration section below

Option 3: Local Development Build

# Clone the repository
git clone https://github.com/hyorimitsu/mcp-amazon-cloudwatch-logs.git
cd mcp-amazon-cloudwatch-logs

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Configure in your AI assistant's configuration
# See Configuration section below

Configuration

Add the server to your AI assistant's configuration:

For npm Installation

{
  "mcpServers": {
    "amazon-cloudwatch-logs": {
      "command": "amazon-cloudwatch-logs-mcp-server",
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "<YOUR_ACCESS_KEY>",
        "AWS_SECRET_ACCESS_KEY": "<YOUR_SECRET_KEY>"
      }
    }
  }
}

For Docker Installation

{
  "mcpServers": {
    "amazon-cloudwatch-logs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "AWS_REGION",
        "-e",
        "AWS_ACCESS_KEY_ID",
        "-e",
        "AWS_SECRET_ACCESS_KEY",
        "ghcr.io/hyorimitsu/mcp-amazon-cloudwatch-logs"
      ],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "<YOUR_ACCESS_KEY>",
        "AWS_SECRET_ACCESS_KEY": "<YOUR_SECRET_KEY>"
      }
    }
  }
}

For Local Development Build

{
  "mcpServers": {
    "amazon-cloudwatch-logs": {
      "command": "node",
      "args": ["/path/to/mcp-amazon-cloudwatch-logs/build/index.js"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "<YOUR_ACCESS_KEY>",
        "AWS_SECRET_ACCESS_KEY": "<YOUR_SECRET_KEY>"
      }
    }
  }
}

Environment Variables

Variable	Required	Description	Default
AWS_REGION	No	The AWS region where your CloudWatch Logs resources are located	us-east-1
AWS_ACCESS_KEY_ID	Yes	Your AWS access key ID for authentication	-
AWS_SECRET_ACCESS_KEY	Yes	Your AWS secret access key for authentication	-
READONLY	No	When set to "true", only read operations are allowed	false

Read-Only Mode

Enable read-only mode by setting the READONLY environment variable to "true":

"env": {
  "AWS_REGION": "us-east-1",
  "AWS_ACCESS_KEY_ID": "<YOUR_ACCESS_KEY>",
  "AWS_SECRET_ACCESS_KEY": "<YOUR_SECRET_KEY>",
  "READONLY": "true"
}

In read-only mode:

• Only READ operations (tools that retrieve or query information) are available
• WRITE operations (tools that create, modify, or delete resources) are disabled

This is useful for scenarios where you want to allow log viewing but prevent any modifications to your CloudWatch Logs resources.

Available Tools

Log Group Operations

Tool Name	Operation Type	Description
create_log_group	WRITE	Creates a new Amazon CloudWatch Logs log group
describe_log_groups	READ	List and describe Amazon CloudWatch Logs log groups
delete_log_group	WRITE	Delete an Amazon CloudWatch Logs log group

Log Stream Operations

Tool Name	Operation Type	Description
create_log_stream	WRITE	Create a new log stream in a log group
describe_log_streams	READ	List and describe log streams in a log group
delete_log_stream	WRITE	Delete a log stream in a log group

Log Event Operations

Tool Name	Operation Type	Description
put_log_events	WRITE	Write log events to a specified log stream
get_log_events	READ	Retrieve log events from a specified log stream
filter_log_events	READ	Search log events with a pattern across log groups

Insights Operations

Tool Name	Operation Type	Description
start_query	READ	Start a CloudWatch Logs Insights query
stop_query	READ	Stop a running CloudWatch Logs Insights query
get_query_results	READ	Retrieve results from a CloudWatch Logs Insights query
describe_queries	READ	List and describe CloudWatch Logs Insights queries

For detailed documentation on each tool, including parameters and examples, see TOOLS.md.

Development

For information on developing and extending this project, please see CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.