s3-mcp

Minimal Model Context Protocol server for S3-compatible storage — AWS S3, RustFS, MinIO, Cloudflare R2, and similar.

• Path-style addressing by default (required for many self-hosted endpoints whose TLS cert does not cover bucket.endpoint subdomains)

• Opt-in self-signed / custom-CA TLS trust, scoped to the S3 client only

• Read-only by default; writes require an explicit flag

• Optional bucket allow-list

• Env vars + CLI flag overrides; secrets stay env-only

Tools

Write tools refuse with a clear error unless S3_ALLOW_WRITE=true (or --allow-write).

Related MCP server: S3 MCP Server

Install / run

npx (recommended)

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["-y", "s3-mcp"],
      "env": {
        "S3_ENDPOINT": "https://rustfs.example.com",
        "S3_ACCESS_KEY_ID": "<key>",
        "S3_SECRET_ACCESS_KEY": "<secret>",
        "S3_REGION": "us-east-1",
        "S3_ALLOW_SELF_SIGNED": "true"
      }
    }
  }
}

A bare --stdio arg is accepted and ignored (drop-in compatible with configs written for s3-mcp-server).

npx straight from GitHub

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["-y", "github:tompetk/s3-mcp"],
      "env": {
        "S3_ENDPOINT": "https://rustfs.example.com",
        "S3_ACCESS_KEY_ID": "<key>",
        "S3_SECRET_ACCESS_KEY": "<secret>",
        "S3_REGION": "us-east-1",
        "S3_ALLOW_SELF_SIGNED": "true"
      }
    }
  }
}

Keep -y: without it npx asks for install confirmation on stdin, which is the MCP transport, so the server never starts. The first run takes roughly 40 seconds because npm installs TypeScript and runs the prepare build; later runs use the npx cache. The published npm package ships prebuilt dist/, so ["-y", "s3-mcp"] starts instantly.

From source

git clone https://github.com/tompetk/s3-mcp.git
cd s3-mcp
npm install
npm run build
node dist/index.js --help

Point your MCP client at node + the absolute path to dist/index.js.

Configuration examples

RustFS / MinIO (self-hosted, often self-signed)

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["-y", "s3-mcp", "--insecure"],
      "env": {
        "S3_ENDPOINT": "https://rustfs.example.com",
        "S3_ACCESS_KEY_ID": "<key>",
        "S3_SECRET_ACCESS_KEY": "<secret>",
        "S3_REGION": "us-east-1",
        "S3_FORCE_PATH_STYLE": "true",
        "S3_ALLOW_WRITE": "false"
      }
    }
  }
}

Prefer a custom CA when you have one:

S3_CA_BUNDLE=/path/to/ca.pem

--insecure / S3_ALLOW_SELF_SIGNED=true disables certificate verification for this client only (never sets NODE_TLS_REJECT_UNAUTHORIZED). Prefer S3_CA_BUNDLE when possible.

Cloudflare R2

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["-y", "s3-mcp", "--no-path-style"],
      "env": {
        "S3_ENDPOINT": "https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
        "S3_ACCESS_KEY_ID": "<key>",
        "S3_SECRET_ACCESS_KEY": "<secret>",
        "S3_REGION": "auto"
      }
    }
  }
}

Environment variables & flags

CLI flags override env vars.

Security

• Read-only by default. Pointing this at production buckets without S3_ALLOW_WRITE cannot mutate data via the MCP tools.

• Bucket allow-list. Set S3_ALLOWED_BUCKETS=prod-logs,prod-artifacts (or repeat --bucket) so the agent cannot touch other buckets the credentials can see.

• TLS. Prefer S3_CA_BUNDLE over --insecure. Self-signed mode is convenient for lab endpoints; it is not a substitute for trusting the right CA.

• Secrets. Keep keys in the MCP client's env block or a secret store — never commit them. .env is gitignored; use .env.example as a template for local smoke tests.

Development

npm install
npm run build
npm run typecheck

# Live round-trip (creates a throwaway bucket unless S3_BUCKET is set)
export S3_ENDPOINT=https://rustfs.example.com
export S3_ACCESS_KEY_ID=...
export S3_SECRET_ACCESS_KEY=...
npm run smoke

# Read-only credentials (list + head + ranged get)
S3_SMOKE_READ_ONLY=true S3_BUCKET=test npm run smoke

Publishing

Tags matching v* trigger GitHub Actions to build and npm publish --provenance --access public. Add an NPM_TOKEN repository secret once.

git tag v1.0.0
git push origin v1.0.0

License

MIT