AWS S3 MCP Server

A Model Context Protocol (MCP) server that exposes AWS S3 operations through a secure, well-defined interface. This server provides tools for listing buckets and objects, and generating presigned URLs for safe data access.

Perfect for integrating S3 with Claude Desktop and other MCP clients!

Features

• List Buckets: Enumerate all S3 buckets in your AWS account
• List Objects: Browse objects within a bucket with optional prefix filtering
• Presigned GET URLs: Generate secure, temporary URLs for downloading objects
• Presigned PUT URLs: Generate secure, temporary URLs for uploading objects (optional, requires ALLOW_WRITE flag)
• Input Validation: All inputs are validated using Zod schemas
• Logging: Structured logging with Pino
• Safe by Default: Write operations are disabled unless explicitly enabled
• Cross-Platform: Works on Windows, Mac, and Linux

🚀 Quick Start

Fastest Setup

# 1. Install and build
npm install
npm run build

# 2. Configure AWS credentials
cp .env.example .env
# Edit .env with your AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION

# 3. Test connection
node examples/quick-test.js

4. Add to Your MCP Client

For Claude Desktop - Edit claude_desktop_config.json:

{
  "mcpServers": {
    "aws-s3": {
      "command": "node",
      "args": ["/absolute/path/to/aws-s3-mcp-server/dist/index.js"]
    }
  }
}

For VS Code - Edit ~/.vscode/mcp.json:

{
  "servers": {
    "aws-s3": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/aws-s3-mcp-server/dist/index.js"]
    }
  }
}

Replace the path with your actual installation directory.

5. Test It

• Claude Desktop: Restart → Ask "List my S3 buckets"
• VS Code: Reload window → @aws-s3 list my buckets

📖 Complete guide: QUICKSTART.md

Documentation

• Setup Guide - Complete installation and configuration instructions
• Usage Guide - How to use with Claude Desktop and examples
• Examples - Sample scripts for download/upload operations

Installation

npm install
npm run build

Configuration

Create a .env file in the root directory (see .env.example):

# Required
AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here
AWS_REGION=us-east-1

# Optional: Enable write operations (presign_put)
ALLOW_WRITE=false

# Optional: Set log level (default: info)
LOG_LEVEL=info

📖 For detailed setup instructions, see SETUP_GUIDE.md

Usage

The server uses stdio transport and communicates via standard input/output, making it suitable for integration with MCP clients like Claude Desktop.

Running Standalone

npm start

Common Operations

List all buckets:

"Show me all my S3 buckets"

List objects in a bucket:

"List all files in my-data-bucket"

Get download link:

"Give me a download link for report.pdf in my-docs-bucket"

Get upload link (if ALLOW_WRITE=true):

"Generate an upload URL for new-file.json in my-bucket"

📖 For complete usage examples, see USAGE_GUIDE.md

Available Tools

1. s3_list_buckets

List all S3 buckets in the AWS account.

Input: None

Example Response:

[
  {
    "name": "my-bucket",
    "creationDate": "2024-01-01T00:00:00.000Z"
  }
]

2. s3_list_objects

List objects in an S3 bucket with optional filtering.

Input:

• bucket (required): The name of the S3 bucket
• prefix (optional): Filter objects by prefix
• maxKeys (optional): Maximum number of objects to return (1-1000)

Example Response:

{
  "objects": [
    {
      "key": "path/to/file.txt",
      "size": 1024,
      "lastModified": "2024-01-01T00:00:00.000Z",
      "etag": "\"abc123\""
    }
  ],
  "isTruncated": false,
  "keyCount": 1
}

3. s3_presign_get

Generate a presigned URL for downloading an object.

Input:

• bucket (required): The name of the S3 bucket
• key (required): The object key
• expiresIn (optional): URL expiration time in seconds (default: 3600, max: 604800)

Example Response:

{
  "url": "https://bucket.s3.amazonaws.com/key?X-Amz-Algorithm=...",
  "expiresIn": 3600,
  "bucket": "my-bucket",
  "key": "path/to/file.txt"
}

4. s3_presign_put

Generate a presigned URL for uploading an object (requires ALLOW_WRITE=true).

Input:

• bucket (required): The name of the S3 bucket
• key (required): The object key
• expiresIn (optional): URL expiration time in seconds (default: 3600, max: 604800)
• contentType (optional): Content type of the object

Example Response:

{
  "url": "https://bucket.s3.amazonaws.com/key?X-Amz-Algorithm=...",
  "expiresIn": 3600,
  "bucket": "my-bucket",
  "key": "path/to/file.txt",
  "contentType": "application/json"
}

Development

Build

npm run build

Watch Mode

npm run dev

Run Tests

npm test

Lint

npm run lint

Quick Connection Test

node examples/quick-test.js

Troubleshooting

Server Not Responding in Claude

1. Check Claude Desktop logs: Help → Show Logs
2. Verify the server path in config is correct (use absolute path)
3. Test manually: node dist/index.js
4. Restart Claude Desktop

AWS Connection Issues

Error: Missing credentials

• Verify .env file exists in project root
• Check no extra spaces in environment variables
• Ensure file is named exactly .env (not .env.txt)

Error: Access Denied

• Verify IAM user has S3 permissions
• Check the bucket exists in the specified region
• Test credentials: node examples/quick-test.js

Error: Invalid Access Key

• Verify AWS_ACCESS_KEY_ID is correct
• Check AWS_SECRET_ACCESS_KEY matches
• Ensure credentials haven't been rotated/deleted

Write Operations Not Working

• Set ALLOW_WRITE=true in .env file
• Restart the MCP server
• Verify IAM user has PutObject permission

Performance Issues

For buckets with millions of objects:

• Use prefix filtering: "List files in my-bucket with prefix 'logs/2024/'"
• Limit results: "Show first 100 files in my-bucket"
• Organize files with prefixes (like folders)

📖 For more troubleshooting, see SETUP_GUIDE.md

Security Best Practices

✅ DO:

• Store credentials in .env file (never commit to git)
• Use IAM users with minimal required permissions
• Disable ALLOW_WRITE unless needed
• Use short expiration times for presigned URLs
• Rotate access keys regularly

❌ DON'T:

• Share presigned URLs publicly
• Use root AWS account credentials
• Commit .env file to version control
• Grant broader permissions than necessary

Project Structure

aws-s3-mcp-server/
├── dist/                 # Compiled JavaScript (generated)
├── src/                  # TypeScript source code
│   ├── index.ts         # Main MCP server
│   └── index.test.ts    # Unit tests
├── examples/            # Example scripts and usage
│   ├── quick-test.js    # AWS connection test
│   ├── test-upload.ps1  # Upload example
│   └── test-download.ps1 # Download example
├── .env.example         # Environment template
├── package.json         # Dependencies
├── tsconfig.json        # TypeScript config
├── README.md           # This file
├── SETUP_GUIDE.md      # Installation guide
└── USAGE_GUIDE.md      # Usage examples

Security

• AWS credentials are loaded from environment variables only
• Write operations (presigned PUT URLs) are disabled by default
• All inputs are validated using Zod schemas
• Presigned URLs have configurable expiration (max 7 days)
• Logs are written to stderr to avoid interfering with stdio transport

Support

• Issues: Report bugs or request features on GitHub
• Setup Help: See SETUP_GUIDE.md
• Usage Help: See USAGE_GUIDE.md
• Examples: Check the examples/ directory

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT

Quick Reference

Need Help? Start with SETUP_GUIDE.md for installation or USAGE_GUIDE.md for examples!