Metadata-Version: 2.4
Name: awslabs.aurora-dsql-mcp-server
Version: 1.0.9
Summary: An AWS Labs Model Context Protocol (MCP) server for Aurora DSQL
Project-URL: homepage, https://awslabs.github.io/mcp/
Project-URL: docs, https://awslabs.github.io/mcp/servers/aurora-dsql-mcp-server/
Project-URL: documentation, https://awslabs.github.io/mcp/servers/aurora-dsql-mcp-server/
Project-URL: repository, https://github.com/awslabs/mcp.git
Project-URL: changelog, https://github.com/awslabs/mcp/blob/main/src/aurora-dsql-mcp-server/CHANGELOG.md
Author: Amazon Web Services, Ram Dwivedula, Yoni Shalom
Author-email: AWSLabs MCP <203918161+awslabs-mcp@users.noreply.github.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: boto3>=1.38.5
Requires-Dist: botocore>=1.38.5
Requires-Dist: httpx>=0.27.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: mcp[cli]>=1.11.0
Requires-Dist: psycopg[binary]>=3.0
Requires-Dist: pydantic>=2.10.6
Description-Content-Type: text/markdown

# AWS Labs Aurora DSQL MCP Server

An AWS Labs Model Context Protocol (MCP) server for Aurora DSQL

## Features

- Converting human-readable questions and commands into structured Postgres-compatible SQL queries and executing them against the configured Aurora DSQL database.
- Read-only by default, transactions enabled with `--allow-writes`
- Connection reuse between requests for improved performance
- Built-in access to Aurora DSQL documentation, search, and best practice recommendations

## Available Tools

### Database Operations

- **readonly_query** - Execute read-only SQL queries against your DSQL cluster
- **transact** - Execute write operations in a transaction (requires `--allow-writes`)
- **get_schema** - Retrieve table schema information

### Documentation and Recommendations

- **dsql_search_documentation** - Search Aurora DSQL documentation
  - Parameters: `search_phrase` (required), `limit` (optional)
- **dsql_read_documentation** - Read specific DSQL documentation pages
  - Parameters: `url` (required), `start_index` (optional), `max_length` (optional)
- **dsql_recommend** - Get recommendations for DSQL best practices
  - Parameters: `url` (required)

## Prerequisites

1. An AWS account with an [Aurora DSQL Cluster](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
1. This MCP server can only be run locally on the same host as your LLM client.
1. Set up AWS credentials with access to AWS services
   - You need an AWS account with appropriate permissions
   - Configure AWS credentials with `aws configure` or environment variables

## Installation

|                                                                                                                                                                                                                                                                        Cursor                                                                                                                                                                                                                                                                         |                                                                                                                                                                                                                                                                                                                                                      VS Code                                                                                                                                                                                                                                                                                                                                                       |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en/install-mcp?name=awslabs.aurora-dsql-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMuYXVyb3JhLWRzcWwtbWNwLXNlcnZlckBsYXRlc3QgLS1jbHVzdGVyX2VuZHBvaW50IFt5b3VyIGRzcWwgY2x1c3RlciBlbmRwb2ludF0gLS1yZWdpb24gW3lvdXIgZHNxbCBjbHVzdGVyIHJlZ2lvbiwgZS5nLiB1cy1lYXN0LTFdIC0tZGF0YWJhc2VfdXNlciBbeW91ciBkc3FsIHVzZXJuYW1lXSAtLXByb2ZpbGUgZGVmYXVsdCIsImVudiI6eyJGQVNUTUNQX0xPR19MRVZFTCI6IkVSUk9SIn0sImRpc2FibGVkIjpmYWxzZSwiYXV0b0FwcHJvdmUiOltdfQ%3D%3D) | [![Install on VS Code](https://img.shields.io/badge/Install_on-VS_Code-FF9900?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Aurora%20DSQL%20MCP%20Server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.aurora-dsql-mcp-server%40latest%22%2C%22--cluster_endpoint%22%2C%22%5Byour%20dsql%20cluster%20endpoint%5D%22%2C%22--region%22%2C%22%5Byour%20dsql%20cluster%20region%2C%20e.g.%20us-east-1%5D%22%2C%22--database_user%22%2C%22%5Byour%20dsql%20username%5D%22%2C%22--profile%22%2C%22default%22%5D%2C%22env%22%3A%7B%22FASTMCP_LOG_LEVEL%22%3A%22ERROR%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D) |

### Using `uv`

1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
2. Install Python using `uv python install 3.10`

Configure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):

```json
{
  "mcpServers": {
    "awslabs.aurora-dsql-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.aurora-dsql-mcp-server@latest",
        "--cluster_endpoint",
        "[your dsql cluster endpoint]",
        "--region",
        "[your dsql cluster region, e.g. us-east-1]",
        "--database_user",
        "[your dsql username]",
        "--profile",
        "default"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Windows Installation

For Windows users, the MCP server configuration format is slightly different:

```json
{
  "mcpServers": {
    "awslabs.aurora-dsql-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.aurora-dsql-mcp-server@latest",
        "awslabs.aurora-dsql-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

### Using Docker

1. 'git clone https://github.com/awslabs/mcp.git'
2. Go to sub-directory 'src/aurora-dsql-mcp-server/'
3. Run 'docker build -t awslabs/aurora-dsql-mcp-server:latest .'
4. Create a env file with temporary credentials:

Either manually:

```file
# fictitious `.env` file with AWS temporary credentials
AWS_ACCESS_KEY_ID=<from the profile you set up>
AWS_SECRET_ACCESS_KEY=<from the profile you set up>
AWS_SESSION_TOKEN=<from the profile you set up>
```

Or using `aws configure`:

```bash
aws configure export-credentials --profile your-profile-name --format env > temp_aws_credentials.env | sed 's/^export //' > temp_aws_credentials.env
```

```json
{
  "mcpServers": {
    "awslabs.aurora-dsql-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/full/path/to/file/above/.env",
        "awslabs/aurora-dsql-mcp-server:latest",
        "--cluster_endpoint",
        "[your data]",
        "--database_user",
        "[your data]",
        "--region",
        "[your data]"
      ]
    }
  }
}
```

## Server Configuration options

### `--allow-writes`

By default, the dsql mcp server does not allow write operations ("read-only mode"). Any invocations of transact tool will fail in this mode. To use transact tool, allow writes by passing `--allow-writes` parameter.

We recommend using least-privilege access when connecting to DSQL. For example, users should use a role that is read-only when possible. The read-only mode has a best-effort client-side enforcement to reject mutations.

### `--cluster_endpoint`

This is mandatory parameter to specify the cluster to connect to. This should be the full endpoint of your cluster, e.g., `01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws`

### `--database_user`

This is a mandatory parameter to specify the user to connect as. For example
`admin`, or `my_user`. Note that the AWS credentials you are using must have
permission to login as that user. For more information on setting up and using
database roles in DSQL, see [Using database roles with IAM roles](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html).

### `--profile`

You can specify the aws profile to use for your credentials. Note that this is
not supported for docker installation.

Using the `AWS_PROFILE` environment variable in your MCP configuration is also
supported:

```json
"env": {
  "AWS_PROFILE": "your-aws-profile"
}
```

If neither is provided, the MCP server defaults to using the "default" profile in your AWS configuration file.

### `--region`

This is a mandatory parameter to specify the region of your DSQL database.

### `--knowledge-server`

Optional parameter to specify the remote MCP server endpoint for DSQL knowledge tools (documentation search, reading, and recommendations).
By default it is pre-configured.

Example:

```bash
--knowledge-server https://custom-knowledge-server.example.com
```

**Note:** For security, only use trusted knowledge server endpoints. The server should be an HTTPS endpoint.

### `--knowledge-timeout`

Optional parameter to specify the timeout in seconds for requests to the knowledge server.

Default: `30.0`

Example:

```bash
--knowledge-timeout 60.0
```

Increase this value if you experience timeouts when accessing documentation on slow networks.

## Development and Testing

### Running Tests

This project includes comprehensive tests to validate the readonly enforcement mechanisms. To run the tests:

```bash
# Install dependencies and run tests
uv run pytest tests/test_readonly_enforcement.py -v

# Run all tests
uv run pytest -v

# Run tests with coverage
uv run pytest --cov=awslabs.aurora_dsql_mcp_server tests/ -v
```

### Local Docker Testing

To test the MCP server locally using Docker:

1. **Build the Docker image:**

   ```bash
   cd src/aurora-dsql-mcp-server
   docker build -t awslabs/aurora-dsql-mcp-server:latest .
   ```

2. **Create AWS credentials file:**

   Option A - Manual creation:

   ```bash
   # Create .env file with your AWS credentials
   cat > .env << EOF
   AWS_ACCESS_KEY_ID=your_access_key_here
   AWS_SECRET_ACCESS_KEY=your_secret_key_here
   AWS_SESSION_TOKEN=your_session_token_here
   EOF
   ```

   Option B - Export from AWS CLI:

   ```bash
   aws configure export-credentials --profile your-profile-name --format env > temp_aws_credentials.env
   sed 's/^export //' temp_aws_credentials.env > .env
   rm temp_aws_credentials.env
   ```

3. **Test the container directly:**

   ```bash
   docker run -i --rm \
     --env-file .env \
     awslabs/aurora-dsql-mcp-server:latest \
     --cluster_endpoint "your-dsql-cluster-endpoint" \
     --database_user "your-username" \
     --region "us-east-1"
   ```

4. **Test with write operations enabled:**
   ```bash
   docker run -i --rm \
     --env-file .env \
     awslabs/aurora-dsql-mcp-server:latest \
     --cluster_endpoint "your-dsql-cluster-endpoint" \
     --database_user "your-username" \
     --region "us-east-1" \
     --allow-writes
   ```

**Note:** Replace the placeholder values with your actual DSQL cluster endpoint, username, and region.
