AWS S3 Tables MCP Server

Warnings

• breaking By default, the S3 Tables MCP server operates in read-only mode. To enable write access (create or append operations on S3 Tables), you must explicitly configure the MCP server with the necessary AWS IAM permissions and use the `--allow-write` flag when starting the server.
  Fix: Grant appropriate IAM permissions to the AWS user/role running the server and launch the server with the `--allow-write` flag (e.g., `uvx awslabs.s3-tables-mcp-server --allow-write`). Always follow the principle of least privilege.
• gotcha Users are solely responsible for the actions and permissions of agents using the MCP server. Misconfigured permissions or unverified agent actions may result in data loss, failed operations, or unexpected LLM behavior.
  Fix: Always follow the principle of least privilege when setting up IAM permissions. If enabling write operations, take a backup of your data and carefully validate any instructions generated by your LLM before execution. Use separate AWS profiles for different environments (dev, test, prod).
• gotcha The Daft engine, utilized by the S3 Tables MCP Server for querying, has strict data type handling. This can lead to failures on numeric operations if real-world datasets have attributes stored as strings that are expected to be numeric.
  Fix: Ensure that your S3 Tables data schemas correctly define data types, and that ingested data conforms to these types. Pre-process data as needed to avoid type mismatches when performing operations that rely on specific data types.
• gotcha The MCP Server for S3 Tables provides a limited set of tools for managing S3 Tables. Specifically, it does not support delete or update operations for table buckets and namespaces, and only supports create, rename, and list for individual tables (no general update or delete).
  Fix: For operations not supported by the MCP Server (e.g., deleting buckets, general table updates), users are advised to use the AWS CLI or AWS SDK for S3 Tables.

Install

• pip install awslabs-s3-tables-mcp-server uv Install library and uv

Quickstart

The `awslabs-s3-tables-mcp-server` operates as a server that AI clients connect to, rather than being directly imported for application development. The quickstart demonstrates how to initiate the server process using `uvx`, a common method for running MCP servers. Ensure AWS credentials are configured in your environment or `~/.aws/credentials` as the server will use them. The server will run indefinitely, typically interacting with AI clients via standard I/O (stdio). This example starts the server and then terminates it after capturing some initial output for demonstration purposes.

import subprocess
import os
import json

# NOTE: Ensure AWS credentials are configured (e.g., via `aws configure` or environment variables).
# The server will pick them up from the environment.
# For example:
# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY')
# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_KEY')
# os.environ['AWS_REGION'] = os.environ.get('AWS_REGION', 'us-east-1')

# 1. Define a minimal mcp_config.json content.
# This configuration tells an MCP client how to start the S3 Tables MCP server.
# In a real scenario, this file would be loaded by an AI client.
# For demonstration, we simulate running the command directly.

mcp_config_content = {
    "mcpServers": {
        "awslabs.s3-tables-mcp-server": {
            "command": "uvx awslabs.s3-tables-mcp-server --profile default --region us-east-1",
            "description": "MCP Server for Amazon S3 Tables",
            "schemas": ["file://~/.config/mcp/awslabs.s3-tables-mcp-server.json"]
        }
    }
}

# 2. To run the server directly, you would typically execute a command.
# This example shows how an AI client might configure and run it.
# For local testing, ensure 'uv' is installed (`pip install uv`).

print("Attempting to run awslabs.s3-tables-mcp-server...")
print("This server typically runs in a long-lived process and interacts with AI clients via stdio.")
print("Press Ctrl+C to stop the server if it starts successfully.")

# Example of how an MCP client would launch the server process
try:
    # The actual command might vary based on your AWS profile and region.
    # Using --allow-write is generally not recommended for quickstart without understanding implications.
    command_to_run = [
        "uvx",
        "awslabs.s3-tables-mcp-server",
        "--profile", os.environ.get('AWS_PROFILE', 'default'), # Use 'default' or actual profile
        "--region", os.environ.get('AWS_REGION', 'us-east-1'), # Use 'us-east-1' or actual region
        # Add --allow-write if you intend to enable write operations, but be cautious!
        # "--allow-write"
    ]
    
    # Starting the server in a non-blocking way for demonstration.
    # In a real setup, this would be managed by the AI client application.
    process = subprocess.Popen(command_to_run, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
    
    print("Server process started (PID: {})".format(process.pid))
    print("Output (first few lines, server runs indefinitely):")
    
    # Read some output to confirm it's running, then terminate for quickstart.
    # In a real scenario, the process would continue running and communicate via stdio.
    for _ in range(5):
        line = process.stdout.readline()
        if line:
            print(line.strip())
        else:
            break

    # For a quickstart, we often don't want a blocking server.
    # You would typically interact with this server via an AI client (e.g., Kiro, Cline).
    # For this example, we'll terminate it after a short period.
    print("\n--- Server started. Terminating quickstart process. ---")
    print("To interact, connect an AI client configured with this server.")
    process.terminate()
    process.wait(timeout=5)

except FileNotFoundError:
    print("Error: 'uvx' command not found. Please ensure 'uv' is installed and in your PATH.")
except Exception as e:
    print(f"An error occurred: {e}")