AWS S3 Connector MCP Server

A production-ready Model Context Protocol (MCP) server for AWS S3 Tables operations.

Provides 16 tools for comprehensive S3 Tables management:

• Table bucket and namespace operations
• Table CRUD and query operations
• Metadata and maintenance management
• Data import (CSV, Parquet, row append)

Supports three transport modes: stdio, SSE, and streamable-http.

Folder Structure

aws-s3-connector-tool/
|-- Dockerfile
|-- LICENSE
|-- mcp.example.json
|-- pyproject.toml
|-- README.md
|-- server.py
|-- tests/
|   |-- __init__.py
|   `-- test_s3_tools.py
`-- tools/
    |-- __init__.py
    |-- s3_connector_tools.py
    `-- toolhandler.py

Available Tools (16)

Table Bucket Management

• create_table_bucket - Create a new S3 table bucket
• list_table_buckets - List all S3 table buckets

Namespace Management

• create_namespace - Create a namespace in a table bucket
• list_namespaces - List all namespaces

Table Operations

• create_table - Create a new S3 table
• list_tables - List all S3 tables
• rename_table - Rename or move a table

Metadata Operations

• get_table_metadata_location - Get table metadata S3 URI
• update_table_metadata_location - Update table metadata location
• get_bucket_metadata_config - Get metadata config for regular S3 bucket

Maintenance Operations

• get_table_maintenance_config - Get table maintenance configuration
• get_maintenance_job_status - Get maintenance job status

Data Operations

• query_database - Execute SQL queries (requires PyIceberg/Daft)
• append_rows_to_table - Append rows to table (requires PyIceberg)
• import_csv_to_table - Import CSV data to table
• import_parquet_to_table - Import Parquet data to table

---

Tools Reference

1. create_table_bucket

Creates an S3 table bucket.

Parameters:

• name (required) - Name of the table bucket (3-63 chars, lowercase letters, numbers, hyphens only)
• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:CreateTableBucket

Example:

{
  "name": "my-data-warehouse",
  "region_name": "us-west-2"
}

Returns:

{
  "status": "success",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse",
  "message": "Table bucket 'my-data-warehouse' created successfully in region us-west-2"
}

---

2. list_table_buckets

List all S3 table buckets for your AWS account.

Parameters:

• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:ListTableBuckets

Example:

{
  "region_name": "us-west-2"
}

Returns:

{
  "status": "success",
  "count": 2,
  "table_buckets": [
    {
      "name": "my-data-warehouse",
      "arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse",
      "createdAt": "2026-05-10T10:30:00Z"
    }
  ]
}

---

3. create_namespace

Creates a namespace in an S3 table bucket. A namespace is a logical grouping of tables.

Parameters:

• namespace (required) - Namespace name (1-255 chars, alphanumeric, underscores, hyphens)
• table_bucket_arn (required) - ARN of the table bucket
• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:CreateNamespace

Example:

{
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse",
  "region_name": "us-west-2"
}

Returns:

{
  "status": "success",
  "namespace": "retail_data",
  "message": "Namespace 'retail_data' created successfully"
}

---

4. list_namespaces

List all namespaces across all S3 table buckets.

Parameters:

• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:ListNamespaces

Example:

{
  "region_name": "us-west-2"
}

Returns:

{
  "status": "success",
  "count": 3,
  "namespaces": [
    {
      "namespace": "retail_data",
      "tableBucketARN": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse"
    }
  ]
}

---

5. create_table

Creates a new S3 table in a namespace. Supports Iceberg format with customizable schema.

Parameters:

• name (required) - Table name (1-255 chars, alphanumeric, underscores, hyphens)
• namespace (required) - Namespace name
• table_bucket_arn (required) - ARN of the table bucket
• format (optional) - Table format (default: ICEBERG)
• metadata (optional) - Table metadata as JSON string (includes schema definition)
• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:CreateTable

Supported Iceberg Types: boolean, int, long, float, double, decimal(P,S), date, time, timestamp, timestamptz, string

Example:

{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse",
  "format": "ICEBERG",
  "metadata": "{\"iceberg\": {\"schema\": {\"type\": \"struct\", \"fields\": [{\"id\": 1, \"name\": \"customer_id\", \"type\": \"long\", \"required\": true}, {\"id\": 2, \"name\": \"customer_name\", \"type\": \"string\", \"required\": false}]}}}"
}

Returns:

{
  "status": "success",
  "table_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse/table/retail_data/customers",
  "version_token": "abc123...",
  "message": "Table 'customers' created successfully in namespace 'retail_data'"
}

---

6. list_tables

List all S3 tables across all table buckets and namespaces.

Parameters:

• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:ListTables

Example:

{
  "region_name": "us-west-2"
}

Returns:

{
  "status": "success",
  "count": 5,
  "tables": [
    {
      "name": "customers",
      "namespace": "retail_data",
      "tableBucketARN": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse",
      "arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse/table/retail_data/customers"
    }
  ]
}

---

7. rename_table

Renames an S3 table or moves it to a different namespace within the same table bucket.

Parameters:

• name (required) - Current table name
• namespace (required) - Current namespace
• table_bucket_arn (required) - ARN of the table bucket
• new_name (optional) - New table name
• new_namespace_name (optional) - New namespace name
• version_token (optional) - Version token for optimistic locking
• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:RenameTable

Example:

{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse",
  "new_name": "customer_profiles",
  "new_namespace_name": "retail_data"
}

Returns:

{
  "status": "success",
  "message": "Table renamed successfully"
}

---

8. get_table_metadata_location

Gets the S3 URI location of the table metadata, which contains the schema and other configuration.

Parameters:

• name (required) - Table name
• namespace (required) - Namespace name
• table_bucket_arn (required) - ARN of the table bucket
• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:GetTableMetadataLocation

Example:

{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse"
}

Returns:

{
  "status": "success",
  "metadata_location": "s3://warehouse-location/metadata/00001-abc123.metadata.json",
  "warehouse_location": "s3://warehouse-location/"
}

---

9. update_table_metadata_location

Updates the metadata location for an S3 table. The metadata location must be an S3 URI within the table's warehouse location.

Parameters:

• name (required) - Table name
• namespace (required) - Namespace name
• table_bucket_arn (required) - ARN of the table bucket
• metadata_location (required) - New metadata location S3 URI (1-2048 chars)
• version_token (required) - Version token for optimistic locking (1-2048 chars)
• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:UpdateTableMetadataLocation

Example:

{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse",
  "metadata_location": "s3://warehouse-location/metadata/00002-def456.metadata.json",
  "version_token": "abc123..."
}

Returns:

{
  "status": "success",
  "message": "Table metadata location updated successfully"
}

---

10. get_bucket_metadata_config

Retrieves the metadata table configuration for a regular general-purpose S3 bucket. S3 Metadata automatically captures object metadata in read-only Apache Iceberg tables.

Parameters:

• bucket (required) - Name of the S3 bucket
• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3:GetBucketMetadataConfiguration

Metadata Table Schema Includes:

• System-defined: bucket, key, size, last_modified_date, storage_class, e_tag, etc.
• Custom metadata: object_tags, user_metadata
• Event metadata: requester, source_ip_address, request_id

Example:

{
  "bucket": "my-general-purpose-bucket",
  "region_name": "us-west-2"
}

Returns:

{
  "status": "success",
  "s3_table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/metadata-bucket",
  "s3_table_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/metadata-bucket/table/...",
  "s3_table_name": "my-general-purpose-bucket-metadata",
  "s3_table_namespace": "s3_metadata"
}

---

11. get_table_maintenance_config

Gets details about the maintenance configuration of a table. S3 Tables maintenance includes compaction and optimization settings.

Parameters:

• name (required) - Table name
• namespace (required) - Namespace name
• table_bucket_arn (required) - ARN of the table bucket
• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:GetTableMaintenanceConfiguration

Example:

{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse"
}

Returns:

{
  "status": "success",
  "configuration": {
    "icebergCompaction": {
      "status": "ENABLED"
    }
  }
}

---

12. get_maintenance_job_status

Gets the status of a maintenance job for a table.

Parameters:

• name (required) - Table name
• namespace (required) - Namespace name
• table_bucket_arn (required) - ARN of the table bucket
• region_name (optional) - AWS region (default: us-west-2)

Required Permission: s3tables:GetTableMaintenanceJobStatus

Example:

{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse"
}

Returns:

{
  "status": "success",
  "job_status": "COMPLETED",
  "details": {
    "startTime": "2026-05-10T10:00:00Z",
    "endTime": "2026-05-10T10:05:00Z"
  }
}

---

13. query_database

Execute SQL queries against S3 Tables using PyIceberg/Daft engine. Provides read-only SQL query capabilities.

Parameters:

• warehouse (required) - Warehouse ARN for Iceberg catalog
• region (required) - AWS region for S3Tables/Iceberg REST endpoint
• namespace (required) - Namespace name (1-255 chars)
• uri (required) - REST URI for Iceberg catalog
• query (optional) - SQL query (default: SELECT * FROM table LIMIT 10)
• catalog_name (optional) - Catalog name
• rest_signing_name (optional) - REST signing name (e.g., s3tables)
• rest_sigv4_enabled (optional) - Enable SigV4 signing (true/false)

Dependencies: Requires pyiceberg and daft packages

Example:

{
  "warehouse": "arn:aws:s3tables:::bucket/my-data-warehouse",
  "region": "us-west-2",
  "namespace": "retail_data",
  "uri": "https://s3tables.us-west-2.amazonaws.com/iceberg",
  "query": "SELECT customer_id, customer_name FROM customers WHERE region = 'US' LIMIT 100",
  "catalog_name": "s3tablescatalog",
  "rest_signing_name": "s3tables",
  "rest_sigv4_enabled": "true"
}

Returns:

{
  "status": "success",
  "rows": [...],
  "row_count": 100
}

---

14. append_rows_to_table

Append rows to an Iceberg table using PyIceberg engine. Rows are provided as a list of dictionaries.

Parameters:

• warehouse (required) - Warehouse ARN for Iceberg catalog
• region (required) - AWS region
• namespace (required) - Namespace name
• table_name (required) - Table name
• uri (required) - REST URI for Iceberg catalog
• rows (required) - Array of row objects (dictionaries)
• catalog_name (optional) - Catalog name
• rest_signing_name (optional) - REST signing name
• rest_sigv4_enabled (optional) - Enable SigV4 signing

Dependencies: Requires pyiceberg package

Required Permission: s3tables:PutTableData

Example:

{
  "warehouse": "arn:aws:s3tables:::bucket/my-data-warehouse",
  "region": "us-west-2",
  "namespace": "retail_data",
  "table_name": "customers",
  "uri": "https://s3tables.us-west-2.amazonaws.com/iceberg",
  "rows": [
    {"customer_id": 1001, "customer_name": "Alice Johnson"},
    {"customer_id": 1002, "customer_name": "Bob Smith"}
  ],
  "catalog_name": "s3tablescatalog",
  "rest_signing_name": "s3tables",
  "rest_sigv4_enabled": "true"
}

Returns:

{
  "status": "success",
  "rows_appended": 2,
  "message": "Successfully appended 2 rows to table"
}

---

15. import_csv_to_table

Import data from a CSV file stored in S3 into an S3 table. If the table doesn't exist, it will be created with inferred schema. If it exists, CSV schema must be compatible.

Parameters:

• warehouse (required) - Warehouse ARN for Iceberg catalog
• region (required) - AWS region
• namespace (required) - Namespace name
• table_name (required) - Table name
• s3_url (required) - S3 URL of CSV file (format: s3://bucket-name/key)
• uri (required) - REST URI for Iceberg catalog
• catalog_name (optional) - Catalog name
• preserve_case (optional) - Preserve column name case (default: false, converts to snake_case)
• rest_signing_name (optional) - REST signing name
• rest_sigv4_enabled (optional) - Enable SigV4 signing

Dependencies: Requires pyiceberg, pandas or daft, and pyarrow

Required Permissions:

• s3:GetObject for the CSV file
• s3tables:GetTable, s3tables:GetTables
• s3tables:PutTableData

Example:

{
  "warehouse": "arn:aws:s3tables:::bucket/my-data-warehouse",
  "region": "us-west-2",
  "namespace": "retail_data",
  "table_name": "customers",
  "s3_url": "s3://my-data-bucket/imports/customers.csv",
  "uri": "https://s3tables.us-west-2.amazonaws.com/iceberg",
  "catalog_name": "s3tablescatalog",
  "preserve_case": false,
  "rest_signing_name": "s3tables",
  "rest_sigv4_enabled": "true"
}

Returns:

{
  "status": "success",
  "message": "Successfully imported 1,543 rows from customers.csv",
  "rows_processed": 1543,
  "file_processed": "customers.csv"
}

---

16. import_parquet_to_table

Import data from a Parquet file stored in S3 into an existing S3 table. The table must already exist and the Parquet schema must be compatible.

Parameters:

• warehouse (required) - Warehouse ARN for Iceberg catalog
• region (required) - AWS region
• namespace (required) - Namespace name
• table_name (required) - Table name (must exist)
• s3_url (required) - S3 URL of Parquet file (format: s3://bucket-name/key)
• uri (required) - REST URI for Iceberg catalog
• catalog_name (optional) - Catalog name
• preserve_case (optional) - Preserve column name case (default: false)
• rest_signing_name (optional) - REST signing name
• rest_sigv4_enabled (optional) - Enable SigV4 signing

Dependencies: Requires pyiceberg, pyarrow or daft

Required Permissions:

• s3:GetObject for the Parquet file
• s3tables:GetTable, s3tables:GetTables
• s3tables:PutTableData

Example:

{
  "warehouse": "arn:aws:s3tables:::bucket/my-data-warehouse",
  "region": "us-west-2",
  "namespace": "retail_data",
  "table_name": "orders",
  "s3_url": "s3://my-data-bucket/imports/orders.parquet",
  "uri": "https://s3tables.us-west-2.amazonaws.com/iceberg",
  "catalog_name": "s3tablescatalog",
  "preserve_case": false,
  "rest_signing_name": "s3tables",
  "rest_sigv4_enabled": "true"
}

Returns:

{
  "status": "success",
  "message": "Successfully imported 8,234 rows from orders.parquet",
  "rows_processed": 8234,
  "file_processed": "orders.parquet"
}

---

Prerequisites

• Python 3.10+
• AWS credentials configured (via environment variables or AWS CLI)
• Appropriate IAM permissions for S3 Tables operations

Installation

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

cd aws-s3-connector-tool

pip install -e .

Run

stdio (default for MCP desktop hosts)

aws-s3-connector-mcp --mode stdio

Or directly:

python server.py --mode stdio

SSE

aws-s3-connector-mcp --mode sse --host 0.0.0.0 --port 8000

Endpoints:

• GET /sse
• POST /messages/

Streamable HTTP

aws-s3-connector-mcp --mode streamable-http --host 0.0.0.0 --port 8000

Endpoint:

• POST /mcp

Health endpoints:

• GET /health
• GET /healthz
• GET /

Docker

# Build image
docker build -t aws-s3-connector-mcp .

# Run (streamable-http default)
docker run -p 8000:8000 \
  -e AWS_ACCESS_KEY_ID=your-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret \
  -e AWS_REGION=us-west-2 \
  aws-s3-connector-mcp

AWS Credentials

The server uses boto3 to interact with AWS services. Configure credentials via:

1. Environment variables:

   • AWS_ACCESS_KEY_ID
   • AWS_SECRET_ACCESS_KEY
   • AWS_REGION (optional, defaults to us-west-2)

2. AWS CLI configuration (~/.aws/credentials)

3. IAM role (when running on EC2/ECS)

Required IAM Permissions

Minimum permissions for basic operations:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3tables:CreateTableBucket",
        "s3tables:ListTableBuckets",
        "s3tables:CreateNamespace",
        "s3tables:ListNamespaces",
        "s3tables:CreateTable",
        "s3tables:ListTables",
        "s3tables:GetTable",
        "s3tables:RenameTable",
        "s3tables:GetTableMetadataLocation",
        "s3tables:UpdateTableMetadataLocation",
        "s3tables:GetTableMaintenanceConfiguration",
        "s3tables:GetTableMaintenanceJobStatus",
        "s3tables:PutTableData",
        "s3:GetObject",
        "s3:GetBucketMetadataConfiguration"
      ],
      "Resource": "*"
    }
  ]
}

Example Usage

Create Table Bucket

{
  "name": "my-table-bucket",
  "region_name": "us-west-2"
}

Create Table

{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-table-bucket",
  "format": "ICEBERG",
  "metadata": "{\"iceberg\": {\"schema\": {...}}}"
}

Query Database

{
  "warehouse": "arn:aws:s3tables:::bucket/my-table-bucket",
  "region": "us-west-2",
  "namespace": "retail_data",
  "uri": "https://s3tables.us-west-2.amazonaws.com/iceberg",
  "query": "SELECT * FROM customers LIMIT 10"
}

Advanced Features

Data Import Tools

The CSV and Parquet import tools require additional dependencies:

• pyiceberg
• pandas or daft
• pyarrow

Install them separately:

pip install pyiceberg pandas pyarrow

Query Execution

The query_database tool requires PyIceberg and Daft for SQL execution against S3 Tables.

MCP Client Configuration

See mcp.example.json for sample client configuration. Update the cwd path to match your installation.

Testing

pip install -e .[dev]
pytest -v

Architecture

MCP Client (Claude/Cursor/VS Code)
    |
    | JSON-RPC 2.0
    v
Transport Layer (stdio | SSE | HTTP)   <- server.py
    |
    v
MCP Server callbacks (list_tools / call_tool)
    |
    v
ToolHandler Registry (16 tools)        <- server.py
    |
    v
AWS S3 Tables Tool Handlers            <- s3_connector_tools.py
    |
    v
boto3 (AWS SDK)
    |
    v
AWS S3 Tables API

Troubleshooting

boto3 not found

pip install boto3

AWS credentials not configured

aws configure
# or set environment variables
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_REGION=us-west-2

Permission denied errors

Verify IAM permissions include all required s3tables actions.

License

MIT License - see LICENSE file for details.