AWS Labs PostgreSQL MCP Server

1.1.1 verified Fri May 01 auth: no python

An AWS Labs Model Context Protocol (MCP) server for PostgreSQL. It provides a lightweight MCP interface to interact with PostgreSQL databases, enabling AI agents to query schemas, execute read-only queries, and retrieve metadata. Current version is 1.1.1 with a fast release cadence. Requires Python >=3.10.

pip install awslabs-postgres-mcp-server

Common errors

error ModuleNotFoundError: No module named 'awslabs-postgres-mcp-server' ↓

cause Attempting to import the package using hyphens, which is invalid in Python.

fix

Use import awslabs_postgres_mcp_server (underscores).

error TypeError: 'port' is an invalid keyword argument for PostgresMCPServer.__init__() ↓

cause Passing `port` to `__init__` is not supported; the constructor expects `port` as a parameter (check version docs). Actually, error arises from mis-match: in v1.0+ `port` must be passed to `run()`? No, corrected: In pre-1.0, `port` was in `run()`. In 1.0+, `port` is in constructor.

fix

Instantiate with PostgresMCPServer(database_url=..., port=8080) and call server.run() without arguments.

Warnings

gotcha The package name on PyPI uses hyphens (awslabs-postgres-mcp-server), but the Python module uses underscores (awslabs_postgres_mcp_server). Many users incorrectly import using hyphens. ↓

fix Use `import awslabs_postgres_mcp_server` (underscores).

breaking Version 1.0.0 introduced a breaking change: the `run()` method no longer accepts a `port` argument; use the constructor parameter instead. ↓

fix Update instantiation: `server = PostgresMCPServer(database_url=..., port=8080)`.

deprecated The parameter `allow_write` is deprecated as of v1.1.0; use `read_only` instead (inverted logic). ↓

fix Use `read_only=True` instead of `allow_write=False`.

Imports

PostgresMCPServer

wrong

from postgres_mcp_server import PostgresMCPServer

correct

from awslabs_postgres_mcp_server import PostgresMCPServer

Package uses underscores, not hyphens, in module name

Quickstart

Creates a read-only MCP server that exposes PostgreSQL schema and query capabilities.

import os
from awslabs_postgres_mcp_server import PostgresMCPServer

# Connection parameters (use env vars for security)
database_url = os.environ.get('DATABASE_URL', 'postgresql://user:pass@localhost:5432/mydb')

# Initialize and run the MCP server
server = PostgresMCPServer(database_url=database_url, read_only=True)
server.run()