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

Resources

Tool Groups

Control which tools are available via the S3_ENABLED_TOOLGROUPS environment variable:

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

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