S3 MCP Server
An Amazon S3 Model Context Protocol (MCP) server that provides tools for interacting with S3 buckets and objects.
https://github.com/user-attachments/assets/d05ff0f1-e2bf-43b9-8d0c-82605abfb666
Overview
This MCP server allows Large Language Models (LLMs) like Claude to interact with AWS S3 storage. It provides tools for:
- Listing available S3 buckets
- Listing objects within a bucket
- Retrieving object contents
The server is built using TypeScript and the MCP SDK, providing a secure and standardized way for LLMs to interface with S3.
Installation
Prerequisites
- Node.js 18 or higher
- npm or yarn
- AWS credentials configured (either through environment variables or AWS credentials file)
Setup
- Install via npm:
- If building from source:
- Configure AWS credentials and S3 access:
Create a `.env` file with your AWS configuration:
Or set these as environment variables.
Configuration
The server can be configured using the following environment variables:
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
Running the Server
You can run the server with Node.js:
Debugging on MCP Inspector
To debug the server using MCP Inspector, you can run `sh run-inspector.sh`
Connecting to Claude Desktop
To use this server with Claude Desktop:
- Edit your Claude Desktop configuration file: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Add the S3 MCP server to the configuration:
**Important**: Please note the following when using the configuration above - Replace `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` with your actual credentials - `S3_BUCKETS` should contain a comma-separated list of buckets you want to allow access to - `AWS_REGION` should be set to the region where your buckets are located
If error occurs on Claude Desktop
If you encounter errors with the above configuration in Claude Desktop, try using absolute paths as follows:
Available Tools
list-buckets
Lists available S3 buckets that the server has permission to access. This tool respects the `S3_BUCKETS` configuration that limits which buckets are shown.
**Parameters:** None
**Example output:**
list-objects
Lists objects in a specified S3 bucket.
**Parameters:**
- `bucket` (required): Name of the S3 bucket to list objects from
- `prefix` (optional): Prefix to filter objects (like a folder path)
- `maxKeys` (optional): Maximum number of objects to return
**Example output:**
get-object
Retrieves an object from a specified S3 bucket. Text files are returned as plain text, while binary files are returned with limited details.
**Parameters:**
- `bucket` (required): Name of the S3 bucket
- `key` (required): Key (path) of the object to retrieve
**Example text output:**
**Example binary output:**
Security Considerations
- The server will only access buckets specified in the `S3_BUCKETS` environment variable
- AWS credentials must have appropriate permissions to the buckets
- Use the principle of least privilege when configuring AWS permissions
- For production use, consider using IAM roles with specific S3 permissions
Usage with Claude
When interacting with Claude in the desktop app, you can ask it to perform S3 operations like:
- "List all my S3 buckets"
- "Summarize PDF files in my-documents-bucket"
- "Get the README.txt file from my-documents-bucket"
Claude will use the appropriate MCP tool to carry out the request and show you the results.
License
MIT