# AWS S3 Connector MCP Server

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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

```text
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 |
|-----------|----------|-------------|
| `s3_url` | Yes (if no credentials) | Public S3 URL, e.g. `https://my-bucket.s3.amazonaws.com` or `s3://my-bucket` |
| `bucket_url` | Alias | Alias of `s3_url` (supported for compatibility) |
| `aws_access_key_id` | No | AWS access key (for private buckets) |
| `aws_secret_access_key` | No | AWS secret key (for private buckets) |
| `region_name` | No | AWS region (default: auto-detected or `us-east-1`) |
| `region` | Alias | Alias of `region_name` (supported for compatibility) |

**Example — public bucket:**
```json
{
  "s3_url": "https://my-public-bucket.s3.amazonaws.com"
}
```

**Example — private bucket:**
```json
{
  "aws_access_key_id": "<access-key>",
  "aws_secret_access_key": "<secret-key>",
  "s3_url": "s3://my-private-bucket",
  "region_name": "us-east-1"
}
```

**Returns:**
```json
{
  "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:**
```json
{}
```

**Returns:**
```json
{
  "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 |
|-----------|----------|-------------|
| `object_key` | Yes | Destination S3 key (path in bucket), e.g. `uploads/file.csv` |
| `key` | Alias | Alias of `object_key` (supported for compatibility) |
| `local_file_path` | No* | Absolute local file path |
| `local_path` | Alias | Alias of `local_file_path` (supported for compatibility) |
| `source_url` | No* | Internet URL to download and upload |

*One of `local_path` or `source_url` is required.

**Example — local file:**
```json
{
  "object_key": "uploads/report.csv",
  "local_file_path": "C:/Users/me/Downloads/report.csv"
}
```

**Example — from URL:**
```json
{
  "object_key": "uploads/data.json",
  "source_url": "https://example.com/data.json"
}
```

**Returns:**
```json
{
  "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 |
|-----------|----------|-------------|
| `object_key` | Yes | S3 object key to read |
| `key` | Alias | Alias of `object_key` (supported for compatibility) |

**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:**
```json
{
  "object_key": "data/report.csv"
}
```

**Returns:**
```json
{
  "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

```bash
# 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)

```bash
aws-s3-connector-mcp --mode stdio
```

### SSE

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

Endpoints:
- `GET  /sse`
- `POST /messages` (also supports `/messages/`)
- `GET  /health`

### Streamable HTTP

```bash
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

```bash
# 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):**
```json
{
  "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:
```json
{}
```

**Streamable HTTP (MCP Inspector / MCPmon):**
```
http://localhost:8000/mcp
```

For SSE in MCP Inspector, use:
```
http://127.0.0.1:8000/sse
```
Avoid `0.0.0.0` in the inspector URL.

---

## Architecture

```text
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](LICENSE) for details.