# mcp-server-s3
[](https://www.npmjs.com/package/mcp-server-s3)
[](https://www.npmjs.com/package/mcp-server-s3)
[](https://github.com/ofershap/mcp-server-s3/actions/workflows/ci.yml)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[](https://agent-plugins.org)
Manage AWS S3 buckets and objects from your AI assistant. Browse files, upload and download content, and generate presigned URLs.
```bash
npx mcp-server-s3
```
> Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP client. Uses your existing AWS credentials (`~/.aws/credentials` or environment variables).
Demo built with remotion-readme-kit
## Why
S3 is the most widely used cloud storage service, but managing it from the command line means remembering `aws s3 ls`, `aws s3 cp`, presigned URL syntax, and various flags. Google has an official MCP for GCS, Cloudflare has one for R2, but AWS S3 doesn't have a polished standalone MCP server on npm. This one lets you ask your assistant to list buckets, download a config file, upload content, or generate a temporary sharing link. It uses the standard AWS credential chain, so if your CLI already works, this works too.
## Tools
| Tool | What it does |
| --------------- | ------------------------------------------------------ |
| `list_buckets` | List all S3 buckets in your AWS account. |
| `list_objects` | List objects in a bucket, with optional prefix filter. |
| `get_object` | Download and read an object's content as text. |
| `put_object` | Upload text content to an S3 object. |
| `delete_object` | Delete an object from a bucket. |
| `presigned_url` | Generate a temporary presigned URL for an object. |
| `bucket_info` | Check if a bucket exists and get basic info. |
## Quick Start
### Cursor
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"s3": {
"command": "npx",
"args": ["mcp-server-s3"],
"env": {
"AWS_REGION": "us-east-1",
"AWS_ACCESS_KEY_ID": "your-access-key",
"AWS_SECRET_ACCESS_KEY": "your-secret-key"
}
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"s3": {
"command": "npx",
"args": ["mcp-server-s3"],
"env": {
"AWS_REGION": "us-east-1",
"AWS_ACCESS_KEY_ID": "your-access-key",
"AWS_SECRET_ACCESS_KEY": "your-secret-key"
}
}
}
}
```
### VS Code
Configure the MCP server to run `npx mcp-server-s3` with `AWS_REGION`, `AWS_ACCESS_KEY_ID`, and `AWS_SECRET_ACCESS_KEY` in the environment.
## Authentication
The server uses the standard AWS credential chain:
1. **Environment variables**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
2. **Shared credentials file**: `~/.aws/credentials`
3. **IAM roles**: when running on EC2, ECS, Lambda, or similar
Set `AWS_REGION` (defaults to `us-east-1`) and make sure your credentials have the necessary S3 permissions: `s3:ListBuckets`, `s3:ListBucket`, `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, `s3:HeadBucket`.
## Agent Plugins
This repo is an [Agent Plugins](https://agent-plugins.org) 1.0.0 package: `plugin.json`, portable `mcp.json`, and `skills/` ship together with the MCP server.
For Cursor, clone the repo and copy or symlink it to `~/.cursor/plugins/local/mcp-server-s3`, then reload the window. Skills and MCP show up under Customize > Plugins.
Agent Plugins v1 does not ship OAuth or AWS SSO wiring. Set `AWS_REGION` and credentials via env or `~/.aws/credentials` in the MCP client host. One-click install is not offered because secrets stay in env.
## FAQ
### What is mcp-server-s3?
An MCP server for S3: list buckets and objects, read/upload text objects, delete keys, presigned URLs, and bucket checks.
### How does authentication work?
Standard AWS credential chain: env vars, shared credentials file, or IAM role on the machine running the MCP server.
### Which env vars should I set in MCP config?
At minimum `AWS_REGION`. Often `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` unless you rely on `~/.aws/credentials` or a role.
### Can I install it as an Agent Plugin in Cursor?
Yes, via `~/.cursor/plugins/local/mcp-server-s3`. Ensure the Cursor process can read the same AWS credentials as your CLI.
### Why no one-click Cursor button?
AWS keys cannot be embedded in a portable install link. Use the JSON under Quick Start.
## Example prompts
- "List all my S3 buckets"
- "Show me the files in my-bucket/uploads/"
- "Download the config.json from my-bucket"
- "Upload this content to my-bucket/notes.txt"
- "Generate a presigned URL for this file that expires in 1 hour"
## Development
```bash
npm install
npm run typecheck
npm run build
npm test
npm run format
npm run lint
```
## See also
More MCP servers and developer tools on my [portfolio](https://gitshow.dev/ofershap).
## Author
[](https://gitshow.dev/ofershap)
[](https://linkedin.com/in/ofershap)
[](https://github.com/ofershap)
---
README built with [README Builder](https://ofershap.github.io/readme-builder/)
## License
MIT © 2026 Ofer Shapira