AWS Logs MCP

This project implements a Model Context Protocol (MCP) server that enables coding assistants like Claude, Cursor, Cline, GitHub Copilot, etc. to access and analyze AWS CloudWatch Logs and CloudTrail events securely. It lets you leverage AI to help troubleshoot AWS issues while keeping your credentials secure.

Overview

Troubleshooting issues in AWS environments often involves sifting through CloudWatch Logs and CloudTrail events. While these services provide valuable information, feeding this information to your vibe coding IDE can be annoying. The AWS Logs MCP server bridges this gap by enabling your code assistant to directly access and analyze your AWS logs, making troubleshooting faster and more intuitive.

What is AWS Logs MCP?

AWS Logs MCP is a server that implements the Model Context Protocol, creating a secure bridge between coding assistants and your AWS logging services. It allows AI models to:

Query your CloudWatch Logs to analyze application behavior
Examine CloudTrail events to understand recent AWS API activity
Filter logs and events using advanced criteria
Securely access AWS using your local credentials

The key advantage is that your AWS credentials remain on your local machine while still allowing AI assistants to help analyze your logs and events.

Available Tools

The AWS Logs MCP server provides four primary tools:

cloudWatchLogGroups

Lists and filters available CloudWatch Log Groups:

// Example usage in an MCP-compatible AI assistant
{
  "tool": "cloudWatchLogGroups",
  "params": {
    "prefix": "/aws/lambda/",
    "limit": 10
  }
}

Response example:

[
  {
    "logGroupName": "/aws/lambda/my-function",
    "creationTime": "2023-01-15T12:30:45.000Z",
    "metricFilterCount": 0,
    "arn": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/my-function:*",
    "storedBytes": 1234567
  }
]

cloudWatchLogs

Retrieves logs from CloudWatch with various filtering options:

{
  "tool": "cloudWatchLogs",
  "params": {
    "logGroupName": "/aws/lambda/my-function",
    "filterPattern": "ERROR",
    "startTime": "-1h",
    "limit": 50
  }
}

Response example:

[2023-01-15T14:30:12.345Z] ERROR: Unable to connect to database
[2023-01-15T14:35:22.678Z] ERROR: Timeout waiting for response from external API

cloudTrailEvents

Retrieves events from CloudTrail with filtering by event name, user, resource, and time:

{
  "tool": "cloudTrailEvents",
  "params": {
    "eventName": "CreateFunction",
    "startTime": "-1d",
    "limit": 25
  }
}

Response example:

[
  {
    "eventTime": "2023-01-15T10:23:45.000Z",
    "eventName": "CreateFunction",
    "username": "admin",
    "resources": [
      {
        "resourceType": "AWS::Lambda::Function",
        "resourceName": "my-new-function"
      }
    ],
    "eventSource": "lambda.amazonaws.com",
    "eventId": "abcdef12-3456-7890-abcd-ef1234567890",
    "readOnly": false
  }
]

testAwsConnection

Verifies AWS credentials and connectivity:

{
  "tool": "testAwsConnection",
  "params": {}
}

Response example:

{
  "success": true,
  "message": "Successfully connected to AWS services",
  "details": {
    "identity": {
      "accountId": "123456789012",
      "arn": "arn:aws:sts::123456789012:assumed-role/MyRole/session-name"
    },
    "services": [
      {
        "name": "CloudWatchLogs",
        "status": "available"
      },
      {
        "name": "CloudTrail",
        "status": "available"
      }
    ]
  }
}

Practical Use Cases

AWS Logs MCP excels in various operational scenarios:

Troubleshooting Application Errors: "Find all error logs from my Lambda function in the last hour"
Security Analysis: "Show me all IAM role changes in the past day"
Deployment Monitoring: "What happened during this ECS service deployment?"
Post-Incident Analysis: "Help me understand what led to this outage"
Resource Tracking: "Which resources were created during this time period?"
Access Pattern Analysis: "Who has been accessing this S3 bucket recently?"

Deployment Options

The AWS Logs MCP server supports two deployment modes:

STDIO Mode (Recommended for IDE/CLI Integration)

This mode works great with VS Code, Claude Code, GitHub Copilot, and other MCP-compatible assistants:

# With AWS profile (recommended)
AWS_PROFILE=your-profile-name npx -y aws-logs-mcp --stdio

For Claude Code specifically:

# Install the aws-logs MCP tool in Claude Code
claude mcp add aws-logs -s user -- npx -y aws-logs-mcp --stdio

HTTP Mode (For Standalone Servers)

This mode is perfect for running as a standalone server or in containerized environments:

# Run as an HTTP server
npx aws-logs-mcp --http

Or with Docker:

docker run -p 3000:3000 -e AWS_PROFILE=default schuettc/aws-logs-mcp --http

Implementation Details

Core Architecture

The AWS Logs MCP server is built with TypeScript and follows a modular design pattern. The main server component creates a flexible MCP server with tool registration for AWS services:

// Main server setup
export class McpServer {
  private tools: Record<string, ToolFunction>;
  private transport: Transport;
 
  constructor(config: ServerConfig) {
    this.tools = {};
    this.transport = createTransport(config.transport);
 
    // Register AWS tools
    this.registerTool("testAwsConnection", testAwsConnection);
    this.registerTool("cloudWatchLogGroups", cloudWatchLogGroups);
    this.registerTool("cloudWatchLogs", cloudWatchLogs);
    this.registerTool("cloudTrailEvents", cloudTrailEvents);
  }
 
  // Start the server
  async start(): Promise<void> {
    this.transport.onRequest(async (request) => {
      try {
        const result = await this.handleRequest(request);
        return result;
      } catch (error) {
        return handleToolError(error);
      }
    });
 
    await this.transport.start();
  }
}

Tool Implementations

Each tool is implemented as a separate module with validation and error handling. For example, the CloudWatch Logs tool:

// CloudWatch Logs tool
export async function cloudWatchLogs(params: {
  logGroupName: string;
  filterPattern?: string;
  startTime?: string;
  endTime?: string;
  limit?: number;
  logStreamName?: string;
}): Promise<any> {
  try {
    // Set up AWS CloudWatch Logs client
    const logs = new CloudWatchLogsClient();
 
    // Parse time parameters
    const { startTime, endTime, limit = 100, logGroupName, filterPattern, logStreamName } = params;
    const timeRange = parseTimeRange(startTime, endTime);
 
    // Prepare filter parameters
    const filterParams = {
      logGroupName,
      filterPattern,
      startTime: timeRange.startTime,
      endTime: timeRange.endTime,
      limit,
    };
 
    if (logStreamName) {
      filterParams.logStreamNames = [logStreamName];
    }
 
    // Execute query and format results
    const command = new FilterLogEventsCommand(filterParams);
    const response = await logs.send(command);
 
    return (response.events || []).map(event => ({
      timestamp: new Date(event.timestamp || 0).toISOString(),
      message: event.message || "",
      logStreamName: event.logStreamName || ""
    }));
  } catch (error) {
    throw formatAwsError(error);
  }
}

Deployment Configuration

The server supports multiple deployment options through a flexible entry point:

// Entry point
async function main() {
  try {
    // Configure error handling
    setupErrorHandlers();
 
    // Load configuration
    const config = loadConfig();
 
    // Set up AWS clients
    await setupAwsClients(config, { tolerateErrors: true });
 
    // Create MCP server with tools
    const server = createMcpServer({
      name: "AWS Logs MCP",
      version: packageInfo.version,
      description: "MCP server for AWS CloudWatch Logs and CloudTrail Events",
      instructions: "Use tools to query AWS CloudWatch Logs and CloudTrail Events"
    });
 
    // Start in appropriate mode (HTTP or STDIO)
    if (config.transport.type === "http") {
      await startHttpServer(server, config);
    } else {
      await server.listen();
    }
  } catch (error) {
    console.error("Error starting server:", error);
    process.exit(1);
  }
}

Security and Authentication

The server securely leverages AWS credentials from your local environment:

// AWS authentication helper
async function setupAwsClients(config, options = { tolerateErrors: false }) {
  try {
    // Configure AWS SDK
    const awsConfig = await loadAwsConfig(config.aws);
 
    // Test connection
    await testAwsConnection({});
 
    console.log("AWS credentials successfully loaded");
    return true;
  } catch (error) {
    if (options.tolerateErrors) {
      console.warn("Warning: AWS credentials not available or invalid");
      console.warn("Some tools may not function correctly");
      return false;
    } else {
      throw error;
    }
  }
}

Conclusion

AWS Logs MCP transforms how developers and operations teams interact with AWS logs and events. By enabling coding assistants to directly access and analyze this data, it makes troubleshooting faster, more intuitive, and more productive. Whether you're debugging a complex distributed system or conducting a security audit, AWS Logs MCP helps you leverage the power of AI to extract valuable insights from your AWS logs.

GitHub Repo

All code available here: https://github.com/schuettc/aws-logs-mcp

More Documentation: https://aws-logs-mcp.subaud.io/