s3-gateway-mcp

An MCP server for S3-compatible storage. It runs once as a Streamable HTTP service, and every agent on your machine (Claude Code, Codex, Cursor, …) shares it. It also speaks stdio when you want a single local process.

• 39 tools covering buckets, objects, versions, policies, CORS, lifecycle, tags, encryption, presigned URLs and multipart cleanup.

• File → public URL in one call. upload_file reads a local path and returns a link you can paste into a PR or issue.

• Credentials stay on the server. Clients only hold a bearer token.

• Works with any S3 API: AWS S3, Cloudflare R2, MinIO, RustFS, Backblaze B2, Wasabi, DigitalOcean Spaces.

Quick start

Docker (recommended)

Build the image, then run it with your settings as environment variables.

git clone https://github.com/jdk1021/s3-gateway-mcp.git
docker build -t s3-gateway-mcp ./s3-gateway-mcp

docker run -d --name s3-gateway-mcp --restart unless-stopped \
  --user "$(id -u):$(id -g)" \
  -p 127.0.0.1:18801:8000 \
  -v /tmp:/tmp:ro \
  -e MCP_TOKEN="$(openssl rand -hex 32)" \
  -e S3_ENDPOINT=https://s3.example.com \
  -e S3_ACCESS_KEY_ID=your_key \
  -e S3_SECRET_ACCESS_KEY=your_secret \
  -e S3_BUCKET=static \
  -e ALLOWED_DIRS=/tmp \
  s3-gateway-mcp

curl -s localhost:18801/health
docker exec s3-gateway-mcp printenv MCP_TOKEN    # token for your agents

Public URLs are built from S3_ENDPOINT (https://s3.example.com/static/<key>). Set S3_PUBLIC_URL only when files are served from a different address such as a CDN. Optional variables are listed under Configuration.

/tmp is mounted read-only at the same path, so a path an agent sees on the host is the path upload_file reads. To allow more, add another -v <dir>:<dir>:ro and append it to ALLOWED_DIRS. Read Local file access before you do.

Docker Compose

git clone https://github.com/jdk1021/s3-gateway-mcp.git && cd s3-gateway-mcp
cp env.example .env          # fill in S3_* and MCP_TOKEN
docker compose up -d --build

Node

npm ci
MCP_TOKEN=... S3_ENDPOINT=... S3_ACCESS_KEY_ID=... S3_SECRET_ACCESS_KEY=... S3_BUCKET=... \
  node src/index.mjs            # HTTP on :8000
node src/index.mjs --stdio      # or stdio

Requires Node.js 20 or later.

Related MCP server: minio-mcp-server

Connect your agents

Claude Code

claude mcp add --transport http -s user s3 http://localhost:18801/mcp \
  --header "Authorization: Bearer $MCP_TOKEN"

Codex (~/.codex/config.toml)

[mcp_servers.s3]
url = "http://localhost:18801/mcp"
http_headers = { Authorization = "Bearer <MCP_TOKEN>" }

Cursor / VS Code / other clients (mcp.json)

{
  "mcpServers": {
    "s3": {
      "type": "http",
      "url": "http://localhost:18801/mcp",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

stdio (no server to run)

claude mcp add -s user s3 \
  -e S3_ENDPOINT=https://s3.example.com -e S3_ACCESS_KEY_ID=... -e S3_SECRET_ACCESS_KEY=... \
  -e S3_BUCKET=static -e ALLOWED_DIRS=/tmp \
  -- node /path/to/s3-gateway-mcp/src/index.mjs --stdio

Configuration

Without a key, uploads are stored as {S3_PATH_PREFIX}YYYYMMDD/<6 hex>-<filename>. Pass key to choose the exact path.

Tools

Every tool takes an optional bucket that falls back to S3_BUCKET. Tools carry MCP readOnlyHint / destructiveHint annotations so clients can ask before destructive calls.

Uploads over 5 MB switch to multipart automatically.

Local file access

• Allow the narrowest directories that hold what agents upload, for example /tmp or a screenshots folder. Avoid $HOME.

• Always mount them read-only (:ro) and at the same path inside the container.

• Symlinks are resolved first, so a link inside an allowed directory cannot point outside it.

• If agents only need to pass bytes they already have, drop the mounts entirely and use upload_base64 or upload_from_url.

Security notes

• The HTTP port binds to 127.0.0.1 in compose.yml. Put a TLS reverse proxy in front before exposing it anywhere else.

• Give the server credentials scoped to the buckets it needs, and combine with S3_ALLOWED_BUCKETS, S3_READ_ONLY or S3_ALLOW_DESTRUCTIVE=false.

• upload_file resolves symlinks and refuses anything outside ALLOWED_DIRS.

• upload_from_url fetches whatever URL it is given, including internal addresses. Leave it out of reach of untrusted prompts.

Design assets

The images in this README are HTML pages in design/, captured with Playwright. Serve the repo root (python3 -m http.server), open /design/hero.html, and append ?lang=ko for the Korean versions.

License

MIT