# AWS Logs MCP

A Model Context Protocol (MCP) server for AWS CloudWatch Logs and CloudTrail Events. This server enables AI assistants to access and query CloudWatch Logs and CloudTrail Events from your AWS environment.

## Overview

AWS Logs MCP connects AI assistants to your AWS environment, allowing them to:

- Query CloudWatch Logs to troubleshoot application issues
- Examine CloudTrail events to understand recent AWS operations
- Filter logs by timestamp, pattern, and log stream
- Monitor log streams during deployments

Your AWS credentials remain on your local machine and are only used for accessing AWS services.

## Installation

### One-Click Installation

Install directly in VS Code:

[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=aws-logs&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_credentials_method%22%2C%22description%22%3A%22AWS%20Authentication%20Method%22%2C%22options%22%3A%5B%22IAM%20Credentials%22%2C%22AWS%20Profile%22%5D%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_profile%22%2C%22description%22%3A%22AWS%20Profile%20Name%22%2C%22default%22%3A%22default%22%2C%22when%22%3A%22%24%7Binput%3Aaws_credentials_method%7D%20%3D%3D%20'AWS%20Profile'%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_access_key_id%22%2C%22description%22%3A%22AWS%20Access%20Key%20ID%22%2C%22password%22%3Atrue%2C%22when%22%3A%22%24%7Binput%3Aaws_credentials_method%7D%20%3D%3D%20'IAM%20Credentials'%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_secret_access_key%22%2C%22description%22%3A%22AWS%20Secret%20Access%20Key%22%2C%22password%22%3Atrue%2C%22when%22%3A%22%24%7Binput%3Aaws_credentials_method%7D%20%3D%3D%20'IAM%20Credentials'%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_region%22%2C%22description%22%3A%22AWS%20Region%22%2C%22default%22%3A%22us-east-1%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40schuettc%2Faws-logs-mcp%22%5D%2C%22env%22%3A%7B%22AWS_PROFILE%22%3A%22%24%7Binput%3Aaws_profile%7D%22%2C%22AWS_ACCESS_KEY_ID%22%3A%22%24%7Binput%3Aaws_access_key_id%7D%22%2C%22AWS_SECRET_ACCESS_KEY%22%3A%22%24%7Binput%3Aaws_secret_access_key%7D%22%2C%22AWS_REGION%22%3A%22%24%7Binput%3Aaws_region%7D%22%7D%7D) [![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Docker-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=aws-logs&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_credentials_method%22%2C%22description%22%3A%22AWS%20Authentication%20Method%22%2C%22options%22%3A%5B%22IAM%20Credentials%22%2C%22AWS%20Profile%22%5D%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_profile%22%2C%22description%22%3A%22AWS%20Profile%20Name%22%2C%22default%22%3A%22default%22%2C%22when%22%3A%22%24%7Binput%3Aaws_credentials_method%7D%20%3D%3D%20'AWS%20Profile'%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_access_key_id%22%2C%22description%22%3A%22AWS%20Access%20Key%20ID%22%2C%22password%22%3Atrue%2C%22when%22%3A%22%24%7Binput%3Aaws_credentials_method%7D%20%3D%3D%20'IAM%20Credentials'%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_secret_access_key%22%2C%22description%22%3A%22AWS%20Secret%20Access%20Key%22%2C%22password%22%3Atrue%2C%22when%22%3A%22%24%7Binput%3Aaws_credentials_method%7D%20%3D%3D%20'IAM%20Credentials'%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22aws_region%22%2C%22description%22%3A%22AWS%20Region%22%2C%22default%22%3A%22us-east-1%22%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22schuettc%2Faws-logs-mcp%22%5D%2C%22env%22%3A%7B%22AWS_PROFILE%22%3A%22%24%7Binput%3Aaws_profile%7D%22%2C%22AWS_ACCESS_KEY_ID%22%3A%22%24%7Binput%3Aaws_access_key_id%7D%22%2C%22AWS_SECRET_ACCESS_KEY%22%3A%22%24%7Binput%3Aaws_secret_access_key%7D%22%2C%22AWS_REGION%22%3A%22%24%7Binput%3Aaws_region%7D%22%7D%7D)

For detailed setup instructions, see the [Installation Guide](getting-started/installation.md).

### Manual Installation

```bash
# Clone the repository
git clone https://github.com/schuettc/aws-logs-mcp.git
cd aws-logs-mcp

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env to configure your AWS credentials

# Build and start the server
pnpm build
pnpm start
```

## Authentication Methods

AWS Logs MCP supports three authentication methods:

1. **AWS Profile**: Uses your existing AWS CLI profiles
2. **IAM Credentials**: Uses access key and secret directly
3. **IAM Role**: Automatically uses instance roles when running on AWS services

## Architecture

![AWS Logs MCP Architecture](images/aws-logs-mcp-architecture.png)

## Available Tools

### CloudWatch Logs Query

Search and filter logs with parameters for:
- Log group name
- Time range
- Pattern matching
- Log stream filtering
- Result limits

### CloudTrail Event Lookup

Query CloudTrail events with filtering by:
- Time range
- Event name
- User identity
- Resource type and ID

## Required AWS Permissions

AWS Logs MCP requires these minimum AWS permissions:

**CloudWatch Logs**:
- `logs:DescribeLogGroups`
- `logs:GetLogEvents`
- `logs:FilterLogEvents`

**CloudTrail**:
- `cloudtrail:LookupEvents`

## Documentation

[Getting Started](getting-started/installation.md) - Installation and configuration  
[Available Tools](usage/available-tools.md) - Tool documentation  
[Architecture Overview](architecture/overview.md) - Technical design  
[Error Handling](guides/error-handling.md) - Error response information  
[Security Best Practices](guides/security-best-practices.md) - Security guidance  
[API Reference](api-reference.md) - API documentation  

## License

MIT-0