Aws S3 Connector

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.py

---

Available Tools (4)

Tool	Description
connect_s3	Connect to an S3 bucket via public URL or AWS credentials
list_objects	List all objects in the connected bucket with filenames and links
upload_object	Upload a file from a local path or internet URL to S3
read_object	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
bucket_url	Yes (if no credentials)	Public S3 URL, e.g. https://my-bucket.s3.amazonaws.com or s3://my-bucket
aws_access_key_id	No	AWS access key (for private buckets)
aws_secret_access_key	No	AWS secret key (for private buckets)
region	No	AWS region (default: auto-detected or us-east-1)

Example — public bucket:

{
  "bucket_url": "https://my-public-bucket.s3.amazonaws.com"
}

Example — private bucket:

{
  "aws_access_key_id": "<access-key>",
  "aws_secret_access_key": "<secret-key>",
  "bucket_url": "s3://my-private-bucket",
  "region": "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
key	Yes	Destination S3 key (path in bucket), e.g. uploads/file.csv
local_path	No*	Absolute local file path
source_url	No*	Internet URL to download and upload

*One of local_path or source_url is required.

Example — local file:

{
  "key": "uploads/report.csv",
  "local_path": "C:/Users/me/Downloads/report.csv"
}

Example — from URL:

{
  "key": "uploads/data.json",
  "source_url": "https://example.com/data.json"
}

Returns:

{
  "status": "success",
  "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
key	Yes	S3 object key to read

Supported formats:

Format	Extensions	Output
Text / CSV / JSON	.txt, .csv, .json, .md, .log, .xml, .html, .yaml, .yml	Raw text
Excel	.xlsx, .xls	JSON rows per sheet
Parquet	.parquet	JSON rows
PDF	.pdf	Extracted text
Images	.png, .jpg, .jpeg, .gif, .webp	Base64-encoded data URL
Other	any	Base64-encoded content

Example:

{
  "key": "data/report.csv"
}

Returns:

{
  "status": "success",
  "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 stdio

SSE

aws-s3-connector-mcp --mode sse --host 0.0.0.0 --port 8000

Endpoints:

• GET /sse
• POST /messages/
• GET /health

Streamable HTTP

aws-s3-connector-mcp --mode streamable-http --host 0.0.0.0 --port 8000

Endpoints:

• POST /mcp
• GET /health
• GET /

Environment variables (alternative to CLI flags)

Variable	Default	Description
TRANSPORT_TYPE	stdio	stdio / sse / streamable-http
APP_HOST	0.0.0.0	Bind host
APP_PORT	8000	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-mcp

---

MCP 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": "<your-access-key>",
        "AWS_SECRET_ACCESS_KEY": "<your-secret-key>",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Streamable HTTP (MCP Inspector / MCPmon):

http://localhost:8000/mcp

---

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 API

---

Troubleshooting

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.