# MCP S3 File Manager
**S3 file operations for AI workflows** - Upload, download, and manage files in Amazon S3 through Model Context Protocol (MCP).
Perfect for AI assistants like Claude, Cursor, and any MCP-compatible client.
## ⚡ Quick Start
```bash
# Install and run (requires AWS credentials)
uvx mcp-s3 --root ~/uploads
# Or install globally
pip install mcp-s3
```
## 🔧 Setup
### 1. AWS Credentials
Create `.env` file in your project:
```bash
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1
S3_BUCKET_NAME=your-bucket-name
```
### 2. Add to Your AI Tool
**Cursor IDE** - Add to `settings.json`:
```json
{
"mcp": {
"servers": {
"s3": {
"command": "uvx",
"args": ["mcp-s3", "--root", "~/uploads"],
"env": {
"AWS_ACCESS_KEY_ID": "your_key",
"AWS_SECRET_ACCESS_KEY": "your_secret",
"S3_BUCKET_NAME": "your-bucket"
}
}
}
}
}
```
**Claude Desktop** - Add to config:
```json
{
"mcpServers": {
"s3": {
"command": "mcp-s3",
"args": ["--root", "~/uploads"],
"env": {
"AWS_ACCESS_KEY_ID": "your_key",
"AWS_SECRET_ACCESS_KEY": "your_secret",
"S3_BUCKET_NAME": "your-bucket"
}
}
}
}
```
## 🛠️ What You Can Do
### Upload Files
```
@mcp Upload my config.json file to S3
@mcp Upload the backup.zip with 2-hour expiration
@mcp Upload report.pdf with force overwrite enabled
```
- **Preserves original filenames** (`config.json` → `config.json`)
- **Prevents accidental overwrites** (fails if file exists)
- **Force overwrite option** for intentional replacements
- **Progress tracking** for large files
### Download Files
```
@mcp Download config.json from S3 to ./downloads/
@mcp Download backup-2024.zip from S3
```
### List Files
```
@mcp List all files in S3
@mcp List files starting with "logs/"
@mcp Show me the first 50 files in the bucket
```
### Get File Info
```
@mcp Get info about config.json in S3
@mcp Show details for backup.zip
```
## 🚀 For Software Engineers
### Common Workflows
**1. Backup & Share Code**
```bash
# Upload project files
@mcp Upload my entire src/ directory to S3
@mcp Generate a 7-day URL for team-config.json
```
**2. CI/CD Integration**
```bash
# In your deployment scripts
mcp-s3 --root ./build upload dist.tar.gz
```
**3. Log Management**
```bash
# Upload application logs
@mcp Upload today's error.log to S3
@mcp List all log files from this month
```
**4. Asset Management**
```bash
# Manage project assets
@mcp Upload design-assets.zip
@mcp Download latest-assets.zip to ./assets/
```
### Development Setup
```bash
git clone https://github.com/dayongd1/mcp-s3.git
cd mcp-s3
uv sync
uv run mcp-s3 --root ~/test-uploads
```
### Testing
```bash
# Test basic functionality
python examples/test_mcp_server.py
# Test naming conflicts
python examples/test_naming_conflicts.py
# Test all features
python examples/test_download.py
python examples/test_list_files.py
python examples/test_get_file_info.py
```
## 🔒 Security Notes
- **Path Safety**: Prevents directory traversal attacks
- **Credential Management**: Uses environment variables (never hardcode keys)
- **Presigned URLs**: Time-limited access (default 24 hours)
- **Conflict Detection**: Prevents accidental file overwrites
## 📦 Installation Options
```bash
# Run without installing (recommended)
uvx mcp-s3
# Install globally
pip install mcp-s3
# Development install
git clone && uv sync
```
## 🚨 Troubleshooting
**"Bucket not found"**
```bash
# Check your bucket name and region
aws s3 ls s3://your-bucket-name
```
**"Access denied"**
```bash
# Verify AWS credentials
python examples/test_aws_connection.py
```
**"File already exists"**
```bash
# Use force overwrite or rename the file
@mcp Upload config.json with force overwrite enabled
```
## 📚 Links
- **PyPI**: https://pypi.org/project/mcp-s3/
- **GitHub**: https://github.com/dayongd1/mcp-s3
- **MCP Docs**: https://modelcontextprotocol.io/
- **AWS S3 Setup**: See `AWS_SETUP_GUIDE.md`
---
**Built with FastMCP** | **Python 3.10+** | **MIT License**
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-s3",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Dayong Huang <dayong.d1@gmail.com>",
"keywords": "aws, fastmcp, file-upload, mcp, model-context-protocol, s3",
"author": null,
"author_email": "Dayong Huang <dayong.d1@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/09/e6/c01956496b968e4f8050f99286a53c998a2b297108485d1f4d36140f13e6/mcp_s3-1.1.0.tar.gz",
"platform": null,
"description": "# MCP S3 File Manager\n\n**S3 file operations for AI workflows** - Upload, download, and manage files in Amazon S3 through Model Context Protocol (MCP).\n\nPerfect for AI assistants like Claude, Cursor, and any MCP-compatible client.\n\n## \u26a1 Quick Start\n\n```bash\n# Install and run (requires AWS credentials)\nuvx mcp-s3 --root ~/uploads\n\n# Or install globally\npip install mcp-s3\n```\n\n## \ud83d\udd27 Setup\n\n### 1. AWS Credentials\nCreate `.env` file in your project:\n```bash\nAWS_ACCESS_KEY_ID=your_access_key\nAWS_SECRET_ACCESS_KEY=your_secret_key\nAWS_DEFAULT_REGION=us-east-1\nS3_BUCKET_NAME=your-bucket-name\n```\n\n### 2. Add to Your AI Tool\n\n**Cursor IDE** - Add to `settings.json`:\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"s3\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-s3\", \"--root\", \"~/uploads\"],\n \"env\": {\n \"AWS_ACCESS_KEY_ID\": \"your_key\",\n \"AWS_SECRET_ACCESS_KEY\": \"your_secret\", \n \"S3_BUCKET_NAME\": \"your-bucket\"\n }\n }\n }\n }\n}\n```\n\n**Claude Desktop** - Add to config:\n```json\n{\n \"mcpServers\": {\n \"s3\": {\n \"command\": \"mcp-s3\",\n \"args\": [\"--root\", \"~/uploads\"],\n \"env\": {\n \"AWS_ACCESS_KEY_ID\": \"your_key\",\n \"AWS_SECRET_ACCESS_KEY\": \"your_secret\",\n \"S3_BUCKET_NAME\": \"your-bucket\"\n }\n }\n }\n}\n```\n\n## \ud83d\udee0\ufe0f What You Can Do\n\n### Upload Files\n```\n@mcp Upload my config.json file to S3\n@mcp Upload the backup.zip with 2-hour expiration\n@mcp Upload report.pdf with force overwrite enabled\n```\n- **Preserves original filenames** (`config.json` \u2192 `config.json`)\n- **Prevents accidental overwrites** (fails if file exists)\n- **Force overwrite option** for intentional replacements\n- **Progress tracking** for large files\n\n### Download Files\n```\n@mcp Download config.json from S3 to ./downloads/\n@mcp Download backup-2024.zip from S3\n```\n\n### List Files\n```\n@mcp List all files in S3\n@mcp List files starting with \"logs/\"\n@mcp Show me the first 50 files in the bucket\n```\n\n### Get File Info\n```\n@mcp Get info about config.json in S3\n@mcp Show details for backup.zip\n```\n\n## \ud83d\ude80 For Software Engineers\n\n### Common Workflows\n\n**1. Backup & Share Code**\n```bash\n# Upload project files\n@mcp Upload my entire src/ directory to S3\n@mcp Generate a 7-day URL for team-config.json\n```\n\n**2. CI/CD Integration**\n```bash\n# In your deployment scripts\nmcp-s3 --root ./build upload dist.tar.gz\n```\n\n**3. Log Management**\n```bash\n# Upload application logs\n@mcp Upload today's error.log to S3\n@mcp List all log files from this month\n```\n\n**4. Asset Management**\n```bash\n# Manage project assets\n@mcp Upload design-assets.zip\n@mcp Download latest-assets.zip to ./assets/\n```\n\n### Development Setup\n```bash\ngit clone https://github.com/dayongd1/mcp-s3.git\ncd mcp-s3\nuv sync\nuv run mcp-s3 --root ~/test-uploads\n```\n\n### Testing\n```bash\n# Test basic functionality\npython examples/test_mcp_server.py\n\n# Test naming conflicts\npython examples/test_naming_conflicts.py\n\n# Test all features\npython examples/test_download.py\npython examples/test_list_files.py\npython examples/test_get_file_info.py\n```\n\n## \ud83d\udd12 Security Notes\n\n- **Path Safety**: Prevents directory traversal attacks\n- **Credential Management**: Uses environment variables (never hardcode keys)\n- **Presigned URLs**: Time-limited access (default 24 hours)\n- **Conflict Detection**: Prevents accidental file overwrites\n\n## \ud83d\udce6 Installation Options\n\n```bash\n# Run without installing (recommended)\nuvx mcp-s3\n\n# Install globally\npip install mcp-s3\n\n# Development install\ngit clone && uv sync\n```\n\n## \ud83d\udea8 Troubleshooting\n\n**\"Bucket not found\"**\n```bash\n# Check your bucket name and region\naws s3 ls s3://your-bucket-name\n```\n\n**\"Access denied\"**\n```bash\n# Verify AWS credentials\npython examples/test_aws_connection.py\n```\n\n**\"File already exists\"**\n```bash\n# Use force overwrite or rename the file\n@mcp Upload config.json with force overwrite enabled\n```\n\n## \ud83d\udcda Links\n\n- **PyPI**: https://pypi.org/project/mcp-s3/\n- **GitHub**: https://github.com/dayongd1/mcp-s3\n- **MCP Docs**: https://modelcontextprotocol.io/\n- **AWS S3 Setup**: See `AWS_SETUP_GUIDE.md`\n\n---\n\n**Built with FastMCP** | **Python 3.10+** | **MIT License**",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP S3 File Uploader - A Model Context Protocol server for S3 uploads",
"version": "1.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/dayongd1/mcp-s3/issues",
"Changelog": "https://github.com/dayongd1/mcp-s3/releases",
"Documentation": "https://github.com/dayongd1/mcp-s3/blob/main/README.md",
"Homepage": "https://github.com/dayongd1/mcp-s3",
"Repository": "https://github.com/dayongd1/mcp-s3"
},
"split_keywords": [
"aws",
" fastmcp",
" file-upload",
" mcp",
" model-context-protocol",
" s3"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2d0908c192ef62a04b077a95d9cac99106b2b69bb6a173afa612ee06c66b765e",
"md5": "2cc714653fe17e36fdb15f9788f6855c",
"sha256": "40895824f3abb0911178361291caee1e18ae8fea7890a653b0ed38b5928f7592"
},
"downloads": -1,
"filename": "mcp_s3-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2cc714653fe17e36fdb15f9788f6855c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8711,
"upload_time": "2025-08-10T19:23:49",
"upload_time_iso_8601": "2025-08-10T19:23:49.602671Z",
"url": "https://files.pythonhosted.org/packages/2d/09/08c192ef62a04b077a95d9cac99106b2b69bb6a173afa612ee06c66b765e/mcp_s3-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "09e6c01956496b968e4f8050f99286a53c998a2b297108485d1f4d36140f13e6",
"md5": "4bdef9277367b9515110f71c00ab7b8e",
"sha256": "cf3b86fd94772804cb61f6826166c6979e5d41a68009bd9c1036ebbd14a757f1"
},
"downloads": -1,
"filename": "mcp_s3-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4bdef9277367b9515110f71c00ab7b8e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10245,
"upload_time": "2025-08-10T19:23:50",
"upload_time_iso_8601": "2025-08-10T19:23:50.761004Z",
"url": "https://files.pythonhosted.org/packages/09/e6/c01956496b968e4f8050f99286a53c998a2b297108485d1f4d36140f13e6/mcp_s3-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 19:23:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dayongd1",
"github_project": "mcp-s3",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "fastmcp",
"specs": [
[
">=",
"0.1.0"
]
]
},
{
"name": "boto3",
"specs": [
[
">=",
"1.26.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "mcp-s3"
}
JSON
