s3-toolbox

The S3 Toolbox MCP Server exposes common AWS S3 operations through a straightforward MCP interface, allowing AI agents and development tools to interact with S3 buckets via natural language or scripted commands. Once the server is running and connected through STDIO transport, clients can issue commands that map to actions such as listing buckets, listing files in a bucket, uploading objects with metadata, downloading objects, retrieving metadata, and deleting objects. The server is built on Spring AI's MCP framework, ensuring a consistent protocol for command/response exchange and easy integration with tools like Cursor IDE or other MCP-enabled assistants.

To use the tools, configure your MCP client to point at the server (via STDIO transport). Your client can then invoke operations by name, supplying the required parameters (e.g., bucketName, key, fileName, contentType) as described in each operation. The server handles the AWS SDK calls behind the scenes, returning results or error details suitable for further processing by your agent or workflow.

Prerequisites:

• Java 21 installed or JDK 21 available
• AWS credentials configured (access key and secret key) or a role with S3 permissions
• Maven (or use the included wrapper)

Installation and setup steps:

1. Clone the repository:

git clone <repository-url>
cd <repository-directory>

2. Build the JAR (recommended using Maven Wrapper): For Windows:

# If the project includes the Maven wrapper
./mvnw.cmd clean package

For Linux/macOS:

./mvnw clean package

Or using a locally installed Maven:

mvn clean package

3. Locate the built JAR (example path):

s3-toolbox-mcp-server-1.0.0.jar

4. Prepare MCP configuration file (mcp-config.json) with the path to the JAR and AWS credentials as needed. Example configuration:

{
  "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"
      }
    }
  }
}

5. Run the server using the configured command and environment. The server will communicate over STDIO with MCP clients.

Tips and notes:

• Ensure Java 21 is installed and available in your PATH.
• Keep AWS credentials secure; prefer role-based access or scoped credentials.
• The server uses STDIO transport; connect your MCP client accordingly (e.g., via Cursor IDE or other compatible tooling).
• The README examples show the typical usage and the required parameters for each S3 operation (list buckets, list files, upload, download, metadata, delete).
• If you encounter authentication errors, verify that AWS_REGION matches the region of your buckets and that the provided keys have the required S3 permissions.
• When deploying, consider using environment-based configuration to avoid embedding credentials in the repo.