dolimovkhumoyun/aws-s3-mcp-server

AWS S3 MCP Server

A simple Model Context Protocol (MCP) server that provides tools for interacting with Amazon S3. This server allows you to list all S3 buckets in your AWS account.

Features

• list_s3_buckets: Get all S3 buckets from your AWS account with their names and creation dates

Prerequisites

• Node.js 18+
• TypeScript
• AWS credentials configured (see AWS Configuration section)

Installation

1. Clone or download this project
2. Install dependencies:

   npm install
   

AWS Configuration

Before using this MCP server, you need to configure your AWS credentials. You can do this in several ways:

Option 1: AWS Credentials File

Create or update ~/.aws/credentials:

[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

Option 2: Environment Variables

export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key
export AWS_REGION=us-east-1  # Optional, defaults to us-east-1

Option 3: AWS Profile

export AWS_PROFILE=your_profile_name

Building and Running

1. Build the TypeScript code:

   npm run build
   

2. Start the server:

   npm start
   

   Or for development with automatic rebuilding:

   npm run dev
   

Usage with MCP Clients

This server communicates over stdio and can be used with any MCP-compatible client. The server provides the following tool:

list_s3_buckets

Description: List all S3 buckets in the AWS account

Input: No parameters required

Output: JSON object containing:

• buckets: Array of bucket objects with name and creationDate
• total: Total number of buckets
• message: Summary message

Example output:

{
  "buckets": [
    {
      "name": "my-bucket-1",
      "creationDate": "2023-01-15T10:30:00.000Z"
    },
    {
      "name": "my-bucket-2", 
      "creationDate": "2023-02-20T14:45:00.000Z"
    }
  ],
  "total": 2,
  "message": "Found 2 S3 bucket(s)"
}

Configuration with Claude Desktop

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

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

Security Notes

• Never commit AWS credentials to version control
• Use IAM roles with minimal required permissions
• Consider using AWS IAM roles for applications when running on EC2
• The server only requires s3:ListAllMyBuckets permission for the list_s3_buckets tool

Development

• npm run build: Compile TypeScript to JavaScript
• npm run dev: Build and run the server
• npm run watch: Watch for changes and rebuild automatically

License

MIT License