aws-s3-connector-mcp
This server provides 4 tools to interact with AWS S3 buckets, supporting both public and private buckets:
connect_s3: Establish a connection to an S3 bucket via a public URL (supporting formats likes3://bucket-name,https://bucket.s3.amazonaws.com) or private access using AWS credentials (access key, secret key, optional session token, and region).list_objects: List objects in the connected bucket, returning file names, sizes, last modified dates, and presigned/public URLs. Supports optional filtering by prefix (folder path) and a result limit.upload_object: Upload files to the connected S3 bucket from either a local file path on the server or a remote internet URL (downloaded then uploaded to a specified S3 key).read_object: Read and return the contents of S3 objects across multiple formats:Text/CSV/JSON/Markup: Raw text content (with optional character limit)
Excel (
.xlsx,.xls): Sheet data as JSON rows (with optional sheet targeting)Parquet: Schema and rows as JSON
PDF: Extracted text from pages
Images (
.png,.jpg,.jpeg,.gif,.webp): Base64-encoded data URLsUnknown/binary: File metadata only
Provides tools for connecting to AWS S3 buckets, listing objects, uploading files, and reading file contents, supporting both public and private buckets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aws-s3-connector-mcp list objects in my S3 bucket"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AWS S3 Connector MCP Server
A production-ready Model Context Protocol (MCP) server for AWS S3 operations.
Provides 4 practical tools for connecting to S3, listing objects, uploading files, and reading file contents — supporting public buckets (no credentials) and private buckets (AWS credentials).
Supports three transport modes: stdio, SSE, and Streamable HTTP.
Folder Structure
aws-s3-connector-tool-updated/
|-- aws_s3_server.py # Main server entry point
|-- Dockerfile
|-- LICENSE
|-- mcp.example.json
|-- pyproject.toml
|-- README.md
`-- tools/
|-- __init__.py
|-- s3_connector_tools.py
`-- toolhandler.pyRelated MCP server: AWS Security MCP Server
Available Tools (4)
Tool | Description |
| Connect to an S3 bucket via public URL or AWS credentials |
| List all objects in the connected bucket with filenames and links |
| Upload a file from a local path or internet URL to S3 |
| Read file contents from S3 (CSV, JSON, Excel, PDF, Parquet, images, text) |
Tools Reference
1. connect_s3
Connect to an S3 bucket. Call this first before using other tools.
Parameters:
Parameter | Required | Description |
| Yes (if no credentials) | Public S3 URL, e.g. |
| Alias | Alias of |
| No | AWS access key (for private buckets) |
| No | AWS secret key (for private buckets) |
| No | AWS region (default: auto-detected or |
| Alias | Alias of |
Example — public bucket:
{
"s3_url": "https://my-public-bucket.s3.amazonaws.com"
}Example — private bucket:
{
"aws_access_key_id": "<access-key>",
"aws_secret_access_key": "<secret-key>",
"s3_url": "s3://my-private-bucket",
"region_name": "us-east-1"
}Returns:
{
"status": "connected",
"bucket": "my-bucket",
"region": "us-east-1",
"mode": "public"
}2. list_objects
List all objects in the connected S3 bucket with filenames and presigned/public links.
Parameters: none (uses connection from connect_s3)
Example:
{}Returns:
{
"status": "success",
"bucket": "my-bucket",
"count": 3,
"objects": [
{
"key": "data/report.csv",
"size": 4096,
"last_modified": "2026-06-01T10:00:00Z",
"url": "https://my-bucket.s3.amazonaws.com/data/report.csv?..."
}
]
}3. upload_object
Upload a file to the connected S3 bucket from a local path or a URL.
Parameters:
Parameter | Required | Description |
| Yes | Destination S3 key (path in bucket), e.g. |
| Alias | Alias of |
| No* | Absolute local file path |
| Alias | Alias of |
| No* | Internet URL to download and upload |
*One of local_path or source_url is required.
Example — local file:
{
"object_key": "uploads/report.csv",
"local_file_path": "C:/Users/me/Downloads/report.csv"
}Example — from URL:
{
"object_key": "uploads/data.json",
"source_url": "https://example.com/data.json"
}Returns:
{
"status": "success",
"object_key": "uploads/report.csv",
"bucket": "my-bucket",
"message": "Uploaded successfully"
}4. read_object
Read and return the contents of a file stored in S3. Supports multiple file formats.
Parameters:
Parameter | Required | Description |
| Yes | S3 object key to read |
| Alias | Alias of |
Supported formats:
Format | Extensions | Output |
Text / CSV / JSON |
| Raw text |
Excel |
| JSON rows per sheet |
Parquet |
| JSON rows |
| Extracted text | |
Images |
| Base64-encoded data URL |
Other | any | Base64-encoded content |
Example:
{
"object_key": "data/report.csv"
}Returns:
{
"status": "success",
"object_key": "data/report.csv",
"format": "text",
"content": "id,name,value\n1,Alice,100\n2,Bob,200\n"
}Prerequisites
Python 3.10+
AWS credentials (only for private buckets)
Installation
# From the workspace root (where .venv lives)
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
cd aws-s3-connector-tool-updated
pip install -e .Run
stdio (default — for MCP desktop clients like Claude Desktop)
aws-s3-connector-mcp --mode stdioSSE
aws-s3-connector-mcp --mode sse --host 0.0.0.0 --port 8000Endpoints:
GET /ssePOST /messages(also supports/messages/)GET /health
Streamable HTTP
aws-s3-connector-mcp --mode streamable-http --host 0.0.0.0 --port 8000Endpoints:
POST /mcpGET /healthGET /
Environment variables (alternative to CLI flags)
Variable | Default | Description |
|
|
|
|
| Bind host |
|
| Bind port |
Docker
# Build
docker build -t aws-s3-connector-mcp .
# Run (streamable-http, port 8000)
docker run -p 8000:8000 \
-e AWS_ACCESS_KEY_ID=<your-key> \
-e AWS_SECRET_ACCESS_KEY=<your-secret> \
aws-s3-connector-mcpMCP Client Configuration
See mcp.example.json for a ready-to-use client config snippet.
stdio (Claude Desktop / Cursor):
{
"mcpServers": {
"aws-s3-connector": {
"command": "aws-s3-connector-mcp",
"args": ["--mode", "stdio"],
"env": {
"AWS_ACCESS_KEY_ID": "AKIA...",
"AWS_SECRET_ACCESS_KEY": "your-secret-key",
"AWS_REGION": "ap-south-1",
"S3_BUCKET": "customer-kyc-demo"
}
}
}
}With this env format, you can run connect_s3 with empty arguments:
{}Streamable HTTP (MCP Inspector / MCPmon):
http://localhost:8000/mcpFor SSE in MCP Inspector, use:
http://127.0.0.1:8000/sseAvoid 0.0.0.0 in the inspector URL.
Architecture
MCP Client (Claude / Cursor / MCP Inspector)
|
| JSON-RPC 2.0
v
Transport Layer (stdio | SSE | Streamable HTTP) ← aws_s3_server.py
|
v
ToolHandler Registry (4 tools)
|
v
S3 Tool Handlers ← tools/s3_connector_tools.py
|
v
boto3 ──► AWS S3 APITroubleshooting
NoCredentialsError — Pass credentials via connect_s3 or set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars.
NoSuchBucket — Verify the bucket name and region in connect_s3.
connect_s3 not called — Always call connect_s3 before list_objects, upload_object, or read_object.
Port already in use — Change APP_PORT env var or use --port flag.
License
MIT License — see LICENSE for details.
Available Tools
4 toolsconnect_s3A
Connect to an AWS S3 bucket. Supports two modes:
Credentials mode (private buckets): provide aws_access_key_id + aws_secret_access_key + region_name.
Public mode (no credentials): provide s3_url only — region is auto-detected from the URL. Accepted s3_url formats: s3://bucket-name, https://bucket.s3.amazonaws.com, https://bucket.s3.REGION.amazonaws.com.
Inputs: s3_url (required), region_name, aws_access_key_id, aws_session_token, +1 more.
list_objectsA
List all objects in the connected S3 bucket. Returns each object's file name, size, last modified date, and a presigned URL. Optionally filter by prefix (folder path) or limit the number of results.
Inputs: prefix, bucket_name, max_results.
read_objectA
Read and display the contents of an object in the connected S3 bucket. Supported formats:
Text: .txt, .csv, .json, .jsonl, .xml, .html, .md, .log, .yaml, .yml
Excel: .xlsx, .xls — returns all sheet data as tables
Parquet: .parquet — returns schema + first 50 rows
PDF: .pdf — extracts text from first 10 pages
Images: .png, .jpg, .jpeg, .gif, .webp — returns image content
Unknown/binary: returns file metadata only.
Inputs: object_key (required), max_chars, sheet_name, bucket_name.
upload_objectA
Upload a file to the connected S3 bucket. Two sources supported:
Local file: provide local_file_path (absolute path on the server).
Internet URL: provide source_url — file is downloaded then uploaded to S3. Optionally set object_key (S3 path/filename). Defaults to the source filename.
Inputs: object_key, source_url, bucket_name, local_file_path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: connect to a bucket, list objects, read object contents, and upload files. There is no overlap in functionality.
All tool names follow a consistent verb_noun pattern with snake_case (connect_s3, list_objects, read_object, upload_object), making them predictable.
With 4 tools covering core S3 operations (connect, list, read, upload), the count is well-scoped and avoids being too few or too many.
The tool surface covers key read and write operations, but is missing a delete operation, which is a minor gap. Overall, it supports common workflows.
Related MCP Connectors
An MCP server for the STRG.com s3-compatible object storage network for all management operations. Full documentation access, ask questions, create buckets, configure scoped access keys, CORS rules, lifecycle policies and perform any S3 operation.
Browse, upload, download, and share files in your S3-compatible buckets with delegated roles.
Browse, upload, download, copy, move and share files in your own S3-compatible buckets.
Tigris MCP Server seamlessly connects AI agents to Tigris bucket and object management.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables interaction with AWS S3 through MCP, supporting bucket and object management, lifecycle configurations, tagging, policies, CORS settings, presigned URLs, and file uploads/downloads.3MIT
- AlicenseNot gradedqualityDmaintenanceEnables management and analysis of AWS security groups, S3 buckets, and VPC connections via MCP.7MIT
- AlicenseNot gradedqualityBmaintenanceProvides MCP tools for AWS S3 and S3-compatible storage, enabling file upload, download, listing, deletion, and temporary remote file staging via natural language.BSD 3-Clause
- AlicenseNot gradedqualityCmaintenanceEnables agents to interact with any S3-compatible storage (AWS S3, LocalStack, MinIO) via MCP, providing tools like list, read, write, delete objects and buckets.MIT