📌Overview

Purpose: The primary goal of the Sample S3 Model Context Protocol Server is to facilitate the retrieval of PDF documents stored in Amazon S3 by exposing them through a structured API.

Overview: This server implementation serves as an interface for accessing AWS S3 data, primarily targeting the integration with large language models (LLMs) by providing a simple way to access documents necessary for context. It supports PDF files and includes a range of tools for bucket and object management within S3.

Key Features:

Resources: Exposes AWS S3 data through GET-like endpoints specifically designed for loading PDF documents into the LLM's context, with a limit of 1000 objects.
ListBuckets: Provides a list of all buckets owned by the authenticated user, enhancing resource management and accessibility.
ListObjectsV2: Fetches one or multiple objects (up to 1,000) from the specified bucket, allowing efficient data retrieval.
GetObject: Retrieves a specific object from S3, supporting both virtual-hosted and path-style requests for flexibility in access methods.

Sample S3 Model Context Protocol Server

An MCP server implementation for retrieving data such as PDFs from S3.

Features

Resources

Expose AWS S3 Data as GET endpoints for loading information into the LLM's context.
Currently supports only PDF documents and is limited to 1000 objects.

Tools

ListBuckets: Returns a list of all buckets owned by the authenticated requester.
ListObjectsV2: Returns up to 1000 objects in a bucket with each request.
GetObject: Retrieves an object from Amazon S3 using the full key name.

Configuration

Setting up AWS Credentials

Obtain AWS access key ID, secret access key, and region from the AWS Management Console.
Configure credentials files using the Default profile.
Ensure these credentials have appropriate READ/WRITE permissions for S3.

Usage with Claude Desktop

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

{
  "mcpServers": {
    "s3-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/user/generative_ai/model_context_protocol/s3-mcp-server",
        "run",
        "s3-mcp-server"
      ]
    }
  }
}

Published Servers Configuration

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

Development

Building and Publishing

Sync dependencies and update lockfile:
```
uv sync
```
Build package distributions:
```
uv build
```
Publish to PyPI:
```
uv publish
```
- Token: --token or UV_PUBLISH_TOKEN
- Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

For the best debugging experience, use the MCP Inspector. Launch it with:

npx @modelcontextprotocol/inspector uv --directory /Users/user/generative_ai/model_context_protocol/s3-mcp-server run s3-mcp-server

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.

sample-mcp-server-s3