AWS S3 MCP Server for PDF Object Retrieval

Overview

This MCP (Model Context Protocol) server exposes PDF objects stored in AWS S3 so they can be loaded into an LLM’s context or streamed to a client. It implements a lightweight MCP backend that maps S3 buckets and objects to MCP Resources and Tools, enabling integrations, testing, and rapid prototyping with real documents stored in S3.

The server is useful when you need to provide an LLM with document context from S3 (for question answering, summarization, or RAG-style pipelines) or when you want a reproducible, local MCP-compatible server for development and integration tests. It supports listing buckets, enumerating objects, and retrieving PDF files (streamed from S3).

Features

• Exposes S3 data as MCP Resources for use in LLM context.
• Supports PDF document retrieval and streaming.
• Tools for bucket/object discovery and object download:
  • ListBuckets
  • ListObjectsV2 (up to 1,000 objects per call)
  • GetObject (retrieve a specific object by key)
• Works with MCP tooling and inspectors for debugging MCP traffic.
• Simple CLI-based packaging and publishing workflow (uv tools).

Note: Current implementation focuses on PDF documents and limits listing to 1,000 objects per request.

Installation / Configuration

Prerequisites:

• Python environment (repository uses uv tooling)
• AWS credentials with S3 access
• Optional: MCP Inspector (Node/npm) for debugging

Clone the repository:

git clone https://github.com/aws-samples/sample-mcp-server-s3.git
cd sample-mcp-server-s3

Set AWS credentials (examples):

Linux / macOS:

export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_ACCESS_KEY"
export AWS_REGION="us-west-2"

Windows (PowerShell):

$env:AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
$env:AWS_SECRET_ACCESS_KEY="YOUR_SECRET_ACCESS_KEY"
$env:AWS_REGION="us-west-2"

Ensure the credentials have S3 permissions such as:

• s3:ListAllMyBuckets
• s3:ListBucket
• s3:GetObject

Run the MCP server locally (development):

# Example using uv runner (project expects uv tooling)
uv --directory /path/to/sample-mcp-server-s3 run s3-mcp-server

Claude Desktop / Client integration examples (add to config):

Development / unpublished server:

{
  "mcpServers": {
    "s3-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/sample-mcp-server-s3",
        "run",
        "s3-mcp-server"
      ]
    }
  }
}

Published server:

{
  "mcpServers": {
    "s3-mcp-server": {
      "command": "uvx",
      "args": [
        "s3-mcp-server"
      ]
    }
  }
}

Building and publishing package:

# Sync deps / update lockfile
uv sync

# Build distributions (source + wheel in dist/)
uv build

# Publish to PyPI (use token or username/password)
uv publish --token $UV_PUBLISH_TOKEN

Available Resources

Resources map to S3 objects exposed to the LLM as document context. The server currently exposes PDF documents and provides metadata such as bucket, key, size, and last modified timestamp. Resource endpoints behave like GET endpoints that the LLM can request to load content.

Limitations:

• PDFs only (no text/HTML/other formats yet)
• Pagination capped to 1,000 objects per ListObjectsV2 call

Available Tools

• ListBuckets
  • Returns all S3 buckets owned by the credentials used.
• ListObjectsV2
  • Enumerates objects in a specific bucket (up to 1,000 per request).
• GetObject
  • Streams or returns the specified object (by full key). Supports virtual-hosted-style and path-style bucket addressing.

Table: Tool -> Purpose

Use Cases

• Context loading for LLM agents: Provide PDF content from S3 as an MCP Resource so an LLM can answer questions about the document.
• Integration testing: Run the MCP server locally to test MCP client implementations without a full backend.
• Streaming large PDFs: Use GetObject to stream PDFs directly from S3 into a consumer that supports chunked transfer or streaming ingestion.
• Bucket auditing / tooling: Quickly list buckets and objects (up to 1,000) to build simple S3-aware tools integrated with LLMs.

Example workflow (LLM client):

1. Call ListBuckets to present available buckets.
2. Call ListObjectsV2 for a chosen bucket to show candidate PDFs.
3. Call GetObject with a selected key to stream the PDF into a document loader and index or feed it to the LLM.

Debugging and Inspector

MCP servers communicate over stdio, which makes debugging harder. Use the MCP Inspector to observe MCP messages and interactions:

npx @modelcontextprotocol/inspector uv --directory /path/to/sample-mcp-server-s3 run s3-mcp-server

The Inspector will expose a local URL where you can visualize requests/responses and diagnose message flows.

License and Security

• Licensed under MIT-0 (see repository LICENSE).
• Configure credentials with least privilege and follow your organization’s secrets handling best practices. For security issues, refer to the repo’s CONTRIBUTING or security contact.