Lets an AI client list, read, upload, copy, and delete S3 buckets and objects with configurable tool access control.
Also known as pulsemcp/mcp-servers, s3-aws-mcp-server
- Stars
- 81
- Tools
- 11
- Downloads, 30 days
- —
- Latest version
- 0.0.5
- Last commit
- Oct 9, 2026
- License
- MIT
What is AWS S3 MCP?
AWS S3 lets an AI client list, read, upload, copy, and delete S3 buckets and objects with configurable tool access control. It exposes 11 tools, such as list_buckets, list_objects, get_object.
Summary generated from the project's README
About AWS S3 MCP server
Managing AWS S3 storage directly from an AI client is possible with this MCP server. It allows developers to perform a variety of bucket and object operations, including listing, reading, uploading, copying, and deleting files. The server is designed for use with local clients like Claude Desktop and requires AWS credentials such as an access key ID and secret access key to function.
Security is a primary focus through configurable tool access control. You can restrict the AI to a readonly group or allow full readwrite capabilities using environment variables. The server also supports single bucket mode, which constrains all operations to one specific bucket by setting the S3_BUCKET variable. This prevents the AI from accessing other parts of your S3 environment.
Beyond standard AWS S3, the server works with S3-compatible endpoints like MinIO or LocalStack. You can fine-tune permissions by enabling or disabling specific tools like delete_object or create_bucket. This level of control ensures that the AI only performs the exact actions you permit within your cloud storage infrastructure.
What you can do with it
- 1Restrict AI to read-only accessConfigure the server so the AI can view files but cannot delete or modify any data.
- 2Isolate operations to one bucketLimit the AI's scope so it can only interact with a single designated bucket.
- 3Manage local S3 development environmentsConnect the AI to a local MinIO instance for testing storage workflows.
Written from the project's README. Every use case is checked against a quote from it.
How to install AWS S3 MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall AWS S3 MCP in Claude Code
$ claude mcp add --env 'AWS_ACCESS_KEY_ID=<YOUR_AWS_ACCESS_KEY_ID>' --env 'AWS_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_ACCESS_KEY>' s3 -- npx -y s3-aws-mcp-serverInstall AWS S3 MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"s3": {
"command": "npx",
"args": [
"-y",
"s3-aws-mcp-server"
],
"env": {
"AWS_ACCESS_KEY_ID": "<YOUR_AWS_ACCESS_KEY_ID>",
"AWS_SECRET_ACCESS_KEY": "<YOUR_AWS_SECRET_ACCESS_KEY>"
}
}
}
}Install AWS S3 MCP in VS Code
.vscode/mcp.json
{
"servers": {
"s3": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"s3-aws-mcp-server"
],
"env": {
"AWS_ACCESS_KEY_ID": "<YOUR_AWS_ACCESS_KEY_ID>",
"AWS_SECRET_ACCESS_KEY": "<YOUR_AWS_SECRET_ACCESS_KEY>"
}
}
}
}Install AWS S3 MCP in VS Code CLI
$ code --add-mcp '{"name":"s3","type":"stdio","command":"npx","args":["-y","s3-aws-mcp-server"],"env":{"AWS_ACCESS_KEY_ID":"<YOUR_AWS_ACCESS_KEY_ID>","AWS_SECRET_ACCESS_KEY":"<YOUR_AWS_SECRET_ACCESS_KEY>"}}'Install AWS S3 MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"s3": {
"command": "npx",
"args": [
"-y",
"s3-aws-mcp-server"
],
"env": {
"AWS_ACCESS_KEY_ID": "<YOUR_AWS_ACCESS_KEY_ID>",
"AWS_SECRET_ACCESS_KEY": "<YOUR_AWS_SECRET_ACCESS_KEY>"
}
}
}
}Install AWS S3 MCP in Codex
$ codex mcp add s3 --env 'AWS_ACCESS_KEY_ID=<YOUR_AWS_ACCESS_KEY_ID>' --env 'AWS_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_ACCESS_KEY>' -- npx -y s3-aws-mcp-serverInstall AWS S3 MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.s3] command = "npx" args = ["-y", "s3-aws-mcp-server"] [mcp_servers.s3.env] AWS_ACCESS_KEY_ID = "<YOUR_AWS_ACCESS_KEY_ID>" AWS_SECRET_ACCESS_KEY = "<YOUR_AWS_SECRET_ACCESS_KEY>"
Install AWS S3 MCP in Gemini CLI
$ gemini mcp add -s user -e 'AWS_ACCESS_KEY_ID=<YOUR_AWS_ACCESS_KEY_ID>' -e 'AWS_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_ACCESS_KEY>' s3 npx -- -y s3-aws-mcp-serverInstall AWS S3 MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"s3": {
"command": "npx",
"args": [
"-y",
"s3-aws-mcp-server"
],
"env": {
"AWS_ACCESS_KEY_ID": "<YOUR_AWS_ACCESS_KEY_ID>",
"AWS_SECRET_ACCESS_KEY": "<YOUR_AWS_SECRET_ACCESS_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
AWS S3 MCP tools 11
Detected from the READMElist_bucketslist_objectsget_objecthead_bucketput_objectdelete_objectcopy_objectcreate_bucketdelete_bucketreadonlyreadwrite
Configuration
AWS_ACCESS_KEY_IDRequiredSecretAWS access key ID for authentication.
AWS_SECRET_ACCESS_KEYRequiredSecretAWS secret access key for authentication.
AWS_ENDPOINT_URLCustom S3 endpoint URL for MinIO or S3-compatible services.
AWS_REGIONAWS region for S3 operations.
S3_BUCKETConstrain all operations to a single bucket.
S3_DISABLED_TOOLSBlacklist specific tools by name.
S3_ENABLED_TOOLGROUPSComma-separated tool groups: readonly or readwrite.
S3_ENABLED_TOOLSWhitelist specific tools by name.
S3_FORCE_PATH_STYLEUse path-style addressing instead of virtual-hosted-style.
SKIP_HEALTH_CHECKSSkip AWS credential validation health checks at startup.
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubS3 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 operationsS3_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 toolsS3_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
bucketparameter 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
AWS S3 MCP questions
How do I add AWS S3 MCP to Claude Code?
Run claude mcp add --env 'AWS_ACCESS_KEY_ID=<YOUR_AWS_ACCESS_KEY_ID>' --env 'AWS_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_ACCESS_KEY>' s3 -- npx -y s3-aws-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add AWS S3 MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does AWS S3 MCP provide?
It exposes 11 tools, including list_buckets, list_objects, get_object, head_bucket, put_object.
Can I restrict the S3 MCP server to read-only operations?
Yes. Set the S3_ENABLED_TOOLGROUPS environment variable to "readonly" to expose only list, get, and head tools.
Does the S3 MCP server work with MinIO or LocalStack?
Yes, it supports S3-compatible endpoints via AWS_ENDPOINT_URL, and you should also set S3_FORCE_PATH_STYLE to true for path-style addressing.
How do I limit the server to a single bucket?
Set the S3_BUCKET environment variable; all object operations are scoped to that bucket and bucket-level tools are hidden.
Which credentials does the server need?
It requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, with AWS_REGION defaulting to us-east-1.
Can I disable specific tools individually?
Yes, use S3_DISABLED_TOOLS to turn off named tools or S3_ENABLED_TOOLS to allow only listed ones.