S3 Reader MCP Server (Streamable HTTP, Cloud Run)

A Model Context Protocol (MCP) server that exposes read-only tools for browsing and reading Amazon S3 objects, served over the streamable-http transport (MCP spec 2025-03-26), ready to deploy on Google Cloud Run.

Tools exposed

Tool	Description
list_buckets	List all S3 buckets visible to the AWS credentials in use
list_objects	List/paginate objects in a bucket, with optional prefix/delimiter
get_object_metadata	HEAD an object: size, content-type, last-modified, etag
read_object_text	Read an object's body as text (size-capped)
read_object_base64	Read an object's raw bytes as base64 (for binary files)
read_pdf_text	Extract readable text from a PDF (page-by-page, with page markers)

The MCP endpoint is served at: POST /mcp (this is the default streamable_http_path from the SDK).

All tools are read-only — nothing in this server can create, overwrite, or delete S3 data.

1. Local setup

pip install -r requirements.txt
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1
export PORT=8080
python server.py

You should see a log line like:

Starting S3 MCP server on 0.0.0.0:8080 (region=us-east-1)

You can also put these values in a local .env file instead of exporting them — server.py loads it automatically via python-dotenv. Never commit .env to source control (it's already excluded in .dockerignore).

2. Test it with MCP Inspector

Before wiring this server up to any AI client, test it directly with the official MCP Inspector — a small web UI that lets you call MCP tools by hand and see the raw request/response. No install needed beyond Node:

npx @modelcontextprotocol/inspector

This opens a local UI (usually at http://localhost:6274). In the connection panel:

1. Transport type: Streamable HTTP
2. URL: http://localhost:8080/mcp (or your Cloud Run URL + /mcp once deployed)
3. If your deployment requires auth (see step 6 below), add an Authorization: Bearer <token> header in the Inspector's headers section.
4. Click Connect, then open the Tools tab — you should see all six tools listed (list_buckets, list_objects, get_object_metadata, read_object_text, read_object_base64, read_pdf_text).
5. Pick a tool, fill in its arguments (e.g. list_buckets needs none; list_objects needs a bucket), and click Run Tool to see the live result against your actual AWS account.

This is the fastest way to confirm the server is reachable, credentials are working, and each tool's schema/response shape looks right — before you point a real MCP client (Claude, another agent, etc.) at it.

If you'd rather stay on the command line, curl also works for a basic smoke test:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

3. AWS credentials & permissions

The server uses boto3's standard credential chain (env vars → shared config → IAM role). Grant the identity used at minimum:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:ListAllMyBuckets", "s3:ListBucket", "s3:GetObject"],
      "Resource": ["arn:aws:s3:::*"]
    }
  ]
}

Scope Resource down to specific bucket ARNs in production.

Recommended for Cloud Run: store AWS credentials in Secret Manager rather than plain environment variables (see step 5 below). If you're running entirely within AWS-adjacent infra, you could alternatively use workload identity federation between GCP and AWS, but the simplest path is an IAM user with an access key stored as a Cloud Run secret.

4. Build and push the container

export PROJECT_ID=your-gcp-project
export REGION=us-central1
export REPO=s3-mcp-server

gcloud auth login
gcloud config set project "$PROJECT_ID"

# One-time: create an Artifact Registry repo
gcloud artifacts repositories create "$REPO" \
  --repository-format=docker \
  --location="$REGION"

# Build with Cloud Build (no local Docker needed) and push
gcloud builds submit \
  --tag "$REGION-docker.pkg.dev/$PROJECT_ID/$REPO/s3-mcp-server:latest"

(Alternatively, build locally with docker build -t ... . and docker push ... if you have Docker installed and are authenticated to Artifact Registry via gcloud auth configure-docker.)

5. Store AWS credentials as secrets

printf '%s' "$AWS_ACCESS_KEY_ID" | gcloud secrets create aws-access-key-id --data-file=-
printf '%s' "$AWS_SECRET_ACCESS_KEY" | gcloud secrets create aws-secret-access-key --data-file=-

6. Deploy to Cloud Run

gcloud run deploy s3-mcp-server \
  --image "$REGION-docker.pkg.dev/$PROJECT_ID/$REPO/s3-mcp-server:latest" \
  --region "$REGION" \
  --platform managed \
  --port 8080 \
  --set-env-vars AWS_REGION=us-east-1 \
  --set-secrets AWS_ACCESS_KEY_ID=aws-access-key-id:latest,AWS_SECRET_ACCESS_KEY=aws-secret-access-key:latest \
  --min-instances 0 \
  --max-instances 5 \
  --no-allow-unauthenticated

Notes:

• --no-allow-unauthenticated requires callers to send a valid Google identity token (Authorization: Bearer <token>). Use --allow-unauthenticated only if you're deploying your own auth in front, since this server exposes read access to your S3 data.
• Cloud Run injects PORT automatically; server.py reads it via os.environ["PORT"], so --port 8080 above must match EXPOSE 8080 in the Dockerfile and the container's listening port (already aligned).
• Because the server is stateless (stateless_http=True), it's safe for Cloud Run to route consecutive requests to different container instances — no sticky sessions required.

7. Connect an MCP client

Point any MCP client that supports the streamable-http transport (including MCP Inspector — see step 2) at:

https://<your-cloud-run-url>/mcp

If the service requires authentication, include a Google-signed identity token as a bearer token, e.g. for quick manual testing:

TOKEN=$(gcloud auth print-identity-token)
curl -X POST https://<your-cloud-run-url>/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Files

• server.py — MCP server implementation (FastMCP, streamable-http transport)
• requirements.txt — Python dependencies
• Dockerfile — container build for Cloud Run
• .dockerignore — build context excludes