# 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

```text
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:**
```json
{
  "name": "my-data-warehouse",
  "region_name": "us-west-2"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "region_name": "us-west-2"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse",
  "region_name": "us-west-2"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "region_name": "us-west-2"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "region_name": "us-west-2"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "bucket": "my-general-purpose-bucket",
  "region_name": "us-west-2"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "name": "customers",
  "namespace": "retail_data",
  "table_bucket_arn": "arn:aws:s3tables:us-west-2:123456789012:bucket/my-data-warehouse"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```bash
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)

```bash
aws-s3-connector-mcp --mode stdio
```

Or directly:

```bash
python server.py --mode stdio
```

### SSE

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

Endpoints:
- GET /sse
- POST /messages/

### Streamable HTTP

```bash
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

```bash
# 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:

```json
{
  "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

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

### Create Table

```json
{
  "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

```json
{
  "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:

```bash
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

```bash
pip install -e .[dev]
pytest -v
```

## Architecture

```text
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
```bash
pip install boto3
```

### AWS credentials not configured
```bash
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.