S3 MCP Server

MCP server for AWS S3 operations with fine-grained tool access control. Supports read/write operations on S3 buckets and objects, with configurable tool groups for security and permission management.

Highlights

• Full S3 bucket and object management (list, get, put, copy, delete)
• Fine-grained access control with tool groups (readonly, readwrite)
• Individual tool enable/disable via environment variables
• AWS credential validation with health checks
• S3-compatible endpoint support (MinIO, LocalStack, etc.)
• TypeScript with strict type checking
• Comprehensive testing (functional, integration, manual)

Capabilities

Tools

Tool	Group	Description
list_buckets	readonly	List all S3 buckets in the AWS account
list_objects	readonly	List objects in a bucket with prefix and pagination
get_object	readonly	Get object contents as text
head_bucket	readonly	Check if a bucket exists and is accessible
put_object	readwrite	Upload or update an object
delete_object	readwrite	Delete an object from a bucket
copy_object	readwrite	Copy an object within or across buckets
create_bucket	readwrite	Create a new S3 bucket
delete_bucket	readwrite	Delete an empty S3 bucket

Resources

Resource	Description
s3://config	Server configuration and status (for debugging)

Tool Groups

Control which tools are available via the S3_ENABLED_TOOLGROUPS environment variable:

Group	Description
readonly	Read-only operations (list, get, head)
readwrite	Write operations (put, delete, copy, create)

Examples:

• S3_ENABLED_TOOLGROUPS="readonly" - Only read operations
• S3_ENABLED_TOOLGROUPS="readonly,readwrite" - All operations
• Not set - All tools enabled (default)

Individual Tool Control

Fine-grained control over specific tools:

• S3_ENABLED_TOOLS="list_buckets,get_object" - Only enable these tools
• S3_DISABLED_TOOLS="delete_bucket,delete_object" - Disable these tools

Single Bucket Mode

Constrain all operations to a specific bucket using S3_BUCKET:

S3_BUCKET="my-bucket"

When set:

• All object operations are automatically scoped to this bucket
• Bucket-level tools (list_buckets, create_bucket, delete_bucket, head_bucket) are hidden
• The bucket parameter is automatically injected and hidden from tool inputs
• For copy_object, both source and destination are constrained to the specified bucket

This is useful for restricting access to a single bucket without giving broader S3 permissions.

Quick Start

Configuration

Environment Variables

Variable	Required	Description	Default
AWS_ACCESS_KEY_ID	Yes	AWS access key ID	-
AWS_SECRET_ACCESS_KEY	Yes	AWS secret access key	-
AWS_REGION	No	AWS region for S3 operations	us-east-1
AWS_ENDPOINT_URL	No	Custom S3 endpoint (for MinIO, etc.)	-
S3_FORCE_PATH_STYLE	No	Use path-style addressing (for MinIO)	false
S3_BUCKET	No	Constrain operations to single bucket	-
S3_ENABLED_TOOLGROUPS	No	Comma-separated tool groups	All enabled
S3_ENABLED_TOOLS	No	Specific tools to enable	-
S3_DISABLED_TOOLS	No	Specific tools to disable	-
SKIP_HEALTH_CHECKS	No	Skip credential validation	false

Claude Desktop Configuration

If this is your first time using MCP Servers, make sure you have the Claude Desktop application and follow the official MCP setup instructions.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["-y", "s3-aws-mcp-server"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-secret-access-key",
        "AWS_REGION": "us-east-1",
        "S3_ENABLED_TOOLGROUPS": "readonly"
      }
    }
  }
}

Restart Claude Desktop and you should be ready to go!

Read-Only Mode

For safer exploration, enable only read operations:

{
  "env": {
    "S3_ENABLED_TOOLGROUPS": "readonly"
  }
}

Using with S3-Compatible Services

For MinIO, LocalStack, or other S3-compatible services:

{
  "env": {
    "AWS_ACCESS_KEY_ID": "minioadmin",
    "AWS_SECRET_ACCESS_KEY": "minioadmin",
    "AWS_REGION": "us-east-1",
    "AWS_ENDPOINT_URL": "http://localhost:9000",
    "S3_FORCE_PATH_STYLE": "true"
  }
}

Note: S3_FORCE_PATH_STYLE is required for MinIO and some other S3-compatible services that use path-style addressing (localhost:9000/bucket-name) instead of virtual-hosted-style (bucket-name.localhost:9000).

Development

Install Dependencies

npm run install-all

Build

npm run build

Running in Development Mode

npm run dev

Testing

# Run functional tests
npm run test:run

# Run integration tests (full MCP protocol)
npm run test:integration

# Run manual tests (real AWS - requires .env)
npm run test:manual:setup  # First time only
npm run test:manual

# Run all automated tests
npm run test:all

Manual Testing Setup

Create a .env file in the s3 directory:

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1

Then run:

npm run test:manual

Project Structure

s3/
├── local/                 # Local server implementation
│   ├── src/
│   │   ├── index.ts      # Main entry point with env validation
│   │   └── index.integration-with-mock.ts
│   └── package.json
├── shared/               # Shared business logic
│   ├── src/
│   │   ├── server.ts     # Server factory with DI
│   │   ├── tools.ts      # Tool registration with grouping
│   │   ├── tools/        # Individual tool implementations
│   │   ├── resources.ts  # Resource implementations
│   │   ├── s3-client/    # AWS S3 client wrapper
│   │   └── logging.ts
│   └── package.json
├── tests/                # Test suite
│   ├── functional/       # Unit tests with mocks
│   ├── integration/      # MCP protocol tests
│   ├── manual/          # Real API tests
│   └── mocks/           # Mock implementations
└── package.json         # Root workspace config

License

MIT