Amazon Aurora Postgres MCP Server

AWS Labs postgres MCP Server

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

Features

Natural language to Postgres SQL query

Converting human-readable questions and commands into structured Postgres-compatible SQL queries and executing them against the configured Aurora Postgres database.

Prerequisites

Install uv from Astral or the GitHub README
Install Python using uv python install 3.10
This MCP server can only be run locally on the same host as your LLM client.
Docker runtime
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

Kiro	Cursor	VS Code

Configure the MCP server in your MCP client configuration (e.g., for Kiro, edit ~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "awslabs.postgres-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.postgres-mcp-server@latest",
        "--allow_write_query"
      ],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windows Installation

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

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

Build and install docker image locally on the same host of your LLM client

'git clone https://github.com/awslabs/mcp.git'
Go to sub-directory 'src/postgres-mcp-server/'
Run 'docker build -t awslabs/postgres-mcp-server:latest .'

Add or update your LLM client's config with following:

Option 1: Using RDS Data API Connection (for Aurora Postgres)

{
  "mcpServers": {
    "awslabs.postgres-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "AWS_ACCESS_KEY_ID=[your data]",
        "-e", "AWS_SECRET_ACCESS_KEY=[your data]",
        "-e", "AWS_REGION=[your data]",
        "awslabs/postgres-mcp-server:latest",
        "--allow_write_query"
      ]
    }
  }
}

NOTE: the MCP config example include --allow_write_query illustrate how to enable write queries. If you want to disable write queries, remove --allow_write_query option.

Support for Database Cluster Creation

You can use the following LLM prompt to create a new Aurora PostgreSQL cluster:

Create an Aurora PostgreSQL cluster named 'mycluster' in us-west-2 region

Connection Methods

The MCP server supports connecting to multiple database endpoints using different connection methods via LLM prompts.

Database Types

APG: Amazon Aurora PostgreSQL
RPG: Amazon RDS for PostgreSQL

Example Prompts

Connect using RDS Data API:

Connect to database named postgres in Aurora PostgreSQL cluster 'my-cluster' with database_type as APG, using rdsapi as connection method in us-west-2 region

Connect using pgwire (Aurora PostgreSQL):

Connect to database named postgres with database endpoint as my-apg17-instance-1.ctgfg6yyo9df.us-west-2.rds.amazonaws.com with database_type as APG, using pgwire as connection method in us-west-2 region

Connect using pgwire (RDS PostgreSQL):

Connect to database named postgres with database endpoint as test-apg17-instance-1.ctgfg6yyo9df.us-west-2.rds.amazonaws.com with database_type as RPG, using pgwire as connection method in us-west-2 region

Supported Connection Methods

Method	Description	Supported Database Types
`pgwire`	Connect to PostgreSQL instance directly using the PostgreSQL wire protocol. Requires proper VPC security group configuration for direct database connectivity.	APG, RPG
`pgwire_iam`	Same as `pgwire`, but uses IAM authentication. Requires IAM authentication to be enabled on the Aurora PostgreSQL cluster.	APG only
`rdsapi`	Connect to Aurora PostgreSQL using the RDS Data API. Requires the RDS Data API to be enabled on the cluster.	APG only

Prerequisites by Connection Method

pgwire / pgwire_iam

VPC security group must allow inbound connections from your MCP server to the database
For pgwire_iam: IAM authentication must be enabled on the Aurora PostgreSQL cluster

rdsapi

RDS Data API must be enabled on the Aurora PostgreSQL cluster
Appropriate IAM permissions for Data API access

AWS Authentication

The MCP server needs AWS credential to read database cluster or instance data, and to to create clusters or instances. These are control plane operations that are separate from Postgres operations (i.e. SELECT, CREATE etc). If you choose to use rdsapi connection method, the AWS credential must have the rds-data:ExecuteStatement permission on the Aurora cluster (see https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonrdsdataapi.html). The MCP uses the AWS profile specified in the AWS_PROFILE environment variable. If not provided, it defaults to the "default" profile in your AWS configuration file.

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

Make sure the AWS profile has permissions to access the RDS data API, and the secret from AWS Secrets Manager. The MCP server creates a boto3 session using the specified profile to authenticate with AWS services. Your AWS IAM credentials remain on your local machine and are strictly used for accessing AWS services.

Postgres Authentication

The MCP server supports IAM and username/password methods for Postgres authentication. You must use AWS secret manager to store the credential and to specify the --secretManagerARN in MCP configuration file.

Security Consideration

`--allow_write_query` read-only enforcement is best effort

When the MCP server runs without --allow_write_query, it enforces a semantic read-only policy. Each query is parsed with pglast (libpg_query — PostgreSQL's own parser). Only read statement shapes (SELECT/WITH … SELECT/VALUES/TABLE/ SHOW/EXPLAIN of a read) are allowed, and known functions whose requested purpose is to mutate sequence, session, statistics, WAL, replication, catalog, large-object, or index state are also rejected even when written as SELECT function(...).

“Read-only” describes the requested operation, not every internal effect of executing it. An ordinary SELECT remains a read even though PostgreSQL updates usage statistics, warms caches, takes snapshots, and acquires transient locks as bookkeeping. By contrast, nextval() intentionally advances a sequence, pg_stat_statements_reset() intentionally destroys statistics, pg_switch_wal() intentionally changes WAL state, and brin_summarize_new_values() persistently updates an index; those are writes. Representative boundaries:

Example	Read-only verdict	Why
ordinary `SELECT`, calculations, `random()`, `clock_timestamp()`, current-XID readers	allow	observes/calculates; engine bookkeeping (including XID assignment) is incidental
`currval()` / `lastval()` / `pg_stat_clear_snapshot()`	allow	observes or refreshes the caller's read snapshot without durable mutation
`pg_prewarm()`	allow	cache-only performance hint; no durable/logical state
replication-slot `peek` / statistics readers	allow	observes without consuming/resetting state
`nextval()` / `setval()`	reject	changes sequence state
`pg_stat_reset*()` / `pg_stat_statements_reset()`	reject	resets collected statistics
WAL, backup, replication-slot/origin management	reject	changes administrative/replication state
BRIN/GIN maintenance and large-object writes	reject	persists index or database data
`cron.schedule()` / `cron.unschedule()`	reject	changes scheduled-job metadata

Regardless of mode, a dangerous set is always rejected — command execution (COPY … TO/FROM PROGRAM), host filesystem access (COPY … TO/FROM '<file>', pg_read_file, lo_import, the pg_ls_dir and adminpack families), SSRF/exfiltration (dblink, aws_lambda.invoke, aws_s3.query_export_to_s3), DoS/corruption/severe server control (pg_sleep, backend termination, advisory lock acquisition, recovery control, pg_surgery, buffer-cache eviction), and settings that disable data-access controls (row_security, session_replication_role) and bulk session resets (RESET ALL, DISCARD ALL) that can restore weaker role/database defaults. Multi-statement input is rejected, and the guard fails closed on parse errors.

Because the guard uses PostgreSQL's own parser, syntactic evasions that defeat text matching — quoted identifiers, comments, and Unicode-escaped identifiers (U&"pg_read_fil\0065") — are decoded and classified exactly as the database would, so they no longer bypass it.

Treat this as a best-effort, defense-in-depth mechanism, not a security boundary. The known-function inventory is versioned to PostgreSQL core through PG18 plus selected PostgreSQL-supplied/common RDS extensions; it is not a complete extension firewall. A parser cannot infer that an arbitrary user-defined or third-party function writes internally, resolve an overloaded operator/function under a custom search_path, or inspect dynamic SQL. Built-in operators are calculations/observations; a user-defined operator can invoke any function and remains role-controlled. In write mode, DO/CREATE FUNCTION bodies and run-time EXECUTE strings are opaque too. Always combine the guard with the least-privilege role below.

TLS is enforced on direct (PG Wire) connections

For direct PostgreSQL connections (the psycopg / PG Wire path, used for IAM auth and Secrets Manager password auth), the server connects with sslmode=verify-full. This requires TLS — there is no silent plaintext downgrade — and verifies both that the server certificate chains to a trusted CA and that its hostname matches, so a credential is never sent in the clear and a man-in-the-middle presenting a spoofed certificate is rejected. (The RDS Data API path already runs over verified HTTPS.)

Aurora / RDS PostgreSQL endpoints present certificates from two different Amazon PKIs, and this server trusts both out of the box:

Amazon RDS private CAs (rds-ca-rsa2048-g1 / rds-ca-rsa4096-g1 / rds-ca-ecc384-g1) — used by direct DB instance / cluster endpoints. See Using SSL/TLS to encrypt a connection to a DB cluster.
Public Amazon Trust Services roots (Amazon Root CA 1–4) — used by endpoints whose certificate is issued by AWS Certificate Manager (ACM), such as RDS Proxy and Aurora Serverless v1.

The package ships the union of both as a single combined bundle (assembled at build time), so verify-full works against any of these endpoints without extra configuration.

The connection is always encrypted — plaintext modes are not offered, so a credential is never sent in the clear. What you can tune is how much of the server's identity is verified, via --sslmode:

`--sslmode`	Encrypted	Verifies CA chain	Verifies hostname	Typical use
`verify-full` (default)	yes	yes	yes	Aurora/RDS via its endpoint (direct instance, cluster, or RDS Proxy); self-hosted with a proper cert + matching hostname
`verify-ca`	yes	yes	no	tunnel / bastion / IP / `localhost` / CNAME where the hostname won't match the cert
`require`	yes	no	no	self-signed cert you don't want to validate; encrypt-only on a trusted network

Certificate verification (the verify-* modes) needs a trusted CA. The combined Amazon bundle described above is used by default. Select a different trust anchor with --ca_bundle:

--ca_bundle /path/to/private-ca.pem   # e.g. self-hosted PostgreSQL with a private CA
--ca_bundle system                    # use the OS trust store (e.g. a publicly-trusted cert)

Self-signed / private-CA notes:

Self-signed or private CA: use --sslmode verify-ca --ca_bundle <cert.pem> (validates the cert against your CA; skips the hostname check that a self-signed cert usually can't satisfy). verify-full also works only if the cert's hostname matches what you connect to.
Don't want to manage a cert file: use --sslmode require (encrypted, no verification; --ca_bundle is ignored).

Because credentials are never sent in cleartext, a server that offers no TLS will fail to connect under any mode. Enable TLS on the server (there is intentionally no plaintext option).

Best practice: run the MCP server as a minimal-privilege Postgres role

The strongest control is to connect the MCP server using a dedicated Postgres role that has only the privileges it actually needs, so that the database itself enforces the boundary regardless of what SQL reaches it. In particular:

Do not connect as a superuser, rds_superuser, or the cluster master user. Those roles bypass row-level security, can read credential catalogs (pg_authid, pg_user_mappings), and can terminate other sessions.
Do not grant the connected role the predefined roles pg_read_server_files, pg_write_server_files, or pg_execute_server_program. These are what make host filesystem access and COPY … TO/FROM PROGRAM command execution possible; without them, the database refuses those operations even if a query reaches it.
Do not grant the connected role USAGE on foreign-data wrappers or foreign servers (GRANT USAGE ON FOREIGN DATA WRAPPER … / ON FOREIGN SERVER …), and do not let it own them. Those privileges are what let a session reach an operator-chosen network endpoint: a read of a foreign table looks like an ordinary SELECT to any SQL filter, so the database's privilege check is the control. postgres_fdw grants no USAGE to non-owners by default — keep it that way.
For read-only use, grant only CONNECT + USAGE + SELECT on the schemas the agent needs, and force read-only transactions at the role level.
For read/write use, grant only the specific INSERT/UPDATE/DELETE privileges required, scoped to the necessary schemas and tables.

Combining a minimal-privilege role (database-enforced) with the blocklist (application-enforced) gives you defense in depth: even if a query slips past the blocklist, the role's privileges still bound what it can do.

The following is an example read-only role:

-- Create a read-only role for Postgres MCP server
CREATE ROLE postgres_mcp_server_readonly WITH LOGIN PASSWORD 'change-me'
    NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION;

-- Allow connection and schema visibility for public schema
-- TODO: add additional schema if required
GRANT CONNECT ON DATABASE mydb TO postgres_mcp_server_readonly;
GRANT USAGE ON SCHEMA public TO postgres_mcp_server_readonly;

-- Read existing tables and sequences for public schema
-- TODO: add additional schema if required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO postgres_mcp_server_readonly;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO postgres_mcp_server_readonly;

-- Read future tables and sequences for public schema
-- TODO: add additional schema if required
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT ON TABLES TO postgres_mcp_server_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT ON SEQUENCES TO postgres_mcp_server_readonly;

-- Force read-only transactions
ALTER ROLE postgres_mcp_server_readonly SET default_transaction_read_only = on;

Least-privilege guardrail (`--privilege_check`)

To make the guidance above hard to get wrong, the server validates the connected role when a connection is established (at startup and via the connect_to_database tool) and can refuse to operate as an over-privileged role — a superuser, a member of rds_superuser, or a role with the BYPASSRLS attribute (which defeats row-level security without being a superuser). This is a guardrail, not the security boundary itself — the database-enforced role privileges remain the real control — but it helps prevent the MCP server from silently running with privileges that would render the blocklist and RLS moot.

The behavior is controlled by the --privilege_check argument:

Value	Behavior
`warn` (default)	Log a warning but allow a connection whose role is over-privileged (superuser, `rds_superuser` member, or `BYPASSRLS`). A connectivity/authentication failure still aborts (the guardrail only relaxes the privilege check, not the need for a working connection).
`enforce`	Reject the connection if the role is over-privileged (superuser, `rds_superuser` member, or `BYPASSRLS`). If the check cannot be performed, the connection is rejected (fail-closed).
`off`	Skip the privilege check entirely (connectivity is still verified).

The default is warn so that upgrades, and the create_cluster bootstrap (which necessarily connects as the rds_superuser master before any least-privilege role exists), do not fail — the over-privileged connection is allowed but a warning is logged. For production, set --privilege_check enforce and connect with a dedicated least-privilege role such as the read-only role above. Under enforce, a violation aborts the server at startup and returns a connection failure through connect_to_database.

The check reads only the connected role's own entry in the pg_roles catalog and tolerates clusters where rds_superuser does not exist (e.g. self-hosted PostgreSQL). Note that on Amazon Aurora the master user is a member of rds_superuser (rather than a raw rolsuper superuser), and the guardrail detects that membership.

Example (add to the args array in your MCP config — recommended for production):

"args": [
  "awslabs.postgres-mcp-server@latest",
  "--privilege_check", "enforce"
]

Features​

Natural language to Postgres SQL query​

Prerequisites​

Installation​

Windows Installation​

Build and install docker image locally on the same host of your LLM client​

Add or update your LLM client's config with following:​

Option 1: Using RDS Data API Connection (for Aurora Postgres)​

Support for Database Cluster Creation​

Connection Methods​

Database Types​

Example Prompts​

Supported Connection Methods​

Prerequisites by Connection Method​

pgwire / pgwire_iam​

rdsapi​

AWS Authentication​

Postgres Authentication​

Security Consideration​

--allow_write_query read-only enforcement is best effort​

TLS is enforced on direct (PG Wire) connections​

Best practice: run the MCP server as a minimal-privilege Postgres role​

Least-privilege guardrail (--privilege_check)​