S3 Toolbox MCP Server

A Model Context Protocol (MCP) server that makes interacting with AWS S3 buckets a breeze. Built using Spring AI MCP, it uses STDIO transport for seamless communication, making it perfect for integration with modern development tools like Cursor IDE and AI agents. This server bridges the gap between your development environment and S3 operations, enabling natural language interactions for both automation tasks and interactive development.

What it does

The S3 Toolbox MCP Server exposes core AWS S3 operations through a simple MCP interface, leveraging Spring AI's Model Context Protocol implementation. This means AI agents can naturally interact with your S3 buckets using plain language, while maintaining precise control over the operations.

Available Tools

The server provides the following S3 operations:

• List Buckets (list_s3_buckets)
  • Lists all available S3 buckets in your account
  • No parameters needed

• List Files (list_s3_files)
  • Lists objects in a specific bucket
  • Parameters:
    • bucketName: Target bucket name
    • prefix: Optional folder path filter

• Upload Files (put_s3_object)
  • Uploads files to S3 with metadata
  • Parameters:
    • bucketName: Target bucket name
    • fileName: Name for the file in S3
    • contentType: MIME type (e.g., 'application/pdf', 'image/png')
    • prefix: Optional path prefix/folder inside the bucket
    • base64Content: File content encoded in Base64 format

• Download Files (get_s3_object)
  • Downloads files from S3
  • Parameters:
    • bucketName: Source bucket
    • key: File path in S3

• Get Metadata (get_s3_object_metadata)
  • Retrieves file metadata
  • Parameters:
    • bucketName: Target bucket
    • key: File path in S3

• Delete Files (delete_s3_object)
  • Removes files from S3
  • Parameters:
    • bucketName: Target bucket
    • key: File to delete

Setup

Prerequisites

• Java 21
• AWS credentials configured
• Maven (or use the included wrapper)

Quick Start

1. Clone the repo:

2. Build the JAR:

Using Maven Wrapper (recommended):

# For Windows
./mvnw.cmd clean package

# For Linux/Mac
./mvnw clean package

Or if you have Maven installed:

mvn clean package

The JAR will be created in the target directory as s3-toolbox-mcp-server-1.0.0.jar

3. Configure your MCP client by creating a configuration file (e.g., mcp-config.json):

{
    "mcpServers": {
      "s3-toolbox-mcp-server": {
            "command": "java",
            "args": [
              "-jar",
              "path/to/s3-toolbox-mcp-server-1.0.0.jar"
            ],
            "env": {
              "AWS_ACCESS_KEY_ID": "your-access-key",
              "AWS_SECRET_ACCESS_KEY": "your-secret-key",
              "AWS_REGION": "us-east-1"
            }
      }
    }
}

Replace the following:

• path/to/s3-toolbox-mcp-server-1.0.0.jar: Full path to the built JAR file (e.g., C:\Users\YourUser\s3-toolbox-mcp-server\target\s3-toolbox-mcp-server-1.0.0.jar)
• your-access-key: Your AWS access key ID
• your-secret-key: Your AWS secret access key
• us-east-1: Your desired AWS region

The server uses STDIO transport for communication with MCP clients, making it easy to integrate with any MCP-compatible client. Once configured, you can use the client to interact with your S3 buckets through natural language commands.

I wanted to bridge the gap between AI agents and S3 operations. While AWS prov

... View full README on GitHub