AWS S3

What is sample-mcp-server-s3?

sample-mcp-server-s3 is a sample Model Context Protocol (MCP) server implementation designed to retrieve data, specifically PDF documents, from AWS S3. It allows Large Language Models (LLMs) to access and utilize information stored in S3 buckets.

How to use sample-mcp-server-s3?

To use sample-mcp-server-s3, you need to configure AWS credentials with appropriate S3 read/write permissions. The server can then be integrated with applications like Claude Desktop by modifying its configuration file to include the MCP server details. For development and debugging, tools like uv and npm with the MCP Inspector can be used.

Key Features of sample-mcp-server-s3

• Resources: Exposes AWS S3 data as "Resources" for LLMs, currently supporting PDF documents and limited to 1000 objects.
• Tools: Provides tools for interacting with S3:
  • ListBuckets: Returns a list of all buckets owned by the authenticated sender.
  • ListObjectsV2: Returns up to 1,000 objects from a specified bucket.
  • GetObject: Retrieves a specific object from S3 using its key name.
• Configuration: Supports flexible configuration for AWS credentials and integration with applications.
• Development Tools: Includes features for building, publishing, and debugging the server.

Use Cases of sample-mcp-server-s3

• LLM Integration: Enables LLMs to access and process documents stored in AWS S3, facilitating context-aware responses and data retrieval.
• Document Analysis: Useful for scenarios where LLMs need to analyze content within PDF documents stored in S3.
• Data Retrieval: Provides a structured way for applications to retrieve specific data from S3 buckets.

FAQ from sample-mcp-server-s3

• What types of documents are supported? Currently, only PDF documents are supported.
• Is there a limit to the number of objects that can be retrieved? Yes, the Resources feature is limited to 1000 objects.
• How do I set up AWS credentials? You need to obtain AWS access key ID, secret access key, and region from the AWS Management Console and configure credentials files using the Default profile.
• How can I debug the MCP server? The MCP Inspector, launched via npm, is recommended for debugging.

Sample S3 Model Context Protocol Server

An MCP server implementation for retrieving data such as PDF's from S3.

Features

Resources

Expose AWS S3 Data through Resources. (think of these sort of like GET endpoints; they are used to load information into the LLM's context). Currently only PDF documents supported and limited to 1000 objects.

Tools

• ListBuckets
  • Returns a list of all buckets owned by the authenticated sender of the request
• ListObjectsV2
  • Returns some or all (up to 1,000) of the objects in a bucket with each request
• GetObject
  • Retrieves an object from Amazon S3. In the GetObject request, specify the full key name for the object. General purpose buckets - Both the virtual-hosted-style requests and the path-style requests are supported

Configuration

Setting up AWS Credentials

1. Obtain AWS access key ID, secret access key, and region from the AWS Management Console and configure credentials files using Default profile as shown here
2. Ensure these credentials have appropriate permission READ/WRITE permissions for S3.

Usage with Claude Desktop

Claude Desktop

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

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

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

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

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

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

Security

See CONTRIBUTING for more information.

License

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