Postgres MCP

What JaviMaligno/postgres_mcp MCP server does

JaviMaligno/postgres_mcp MCP server connects MCP-compatible clients to PostgreSQL databases. It provides tools for running read-only SQL, inspecting database structure, examining indexes and constraints, reviewing table statistics, and retrieving database information. The server also includes an optional write tool for INSERT, UPDATE, and DELETE operations when write access is enabled.

The repository contains equivalent TypeScript and Python implementations. The TypeScript package is the recommended option for Smithery deployments and requires Node.js 20 or newer. The Python package requires Python 3.10 or newer. Both implementations support the documented MCP protocol revision and retain compatibility with clients using the earlier initialization style.

How it works

JaviMaligno/postgres_mcp MCP server reads connection settings from the process environment rather than accepting credentials as tool arguments. A single connection can use PostgreSQL host, port, user, password, database, and SSL mode variables. For multiple databases, POSTGRES_CONNECTIONS defines named aliases; each tool can select an alias with its optional database argument, while omitted arguments use the configured default.

Multiple connections are opened lazily, so an unused configured database does not open a connection pool. The server can also apply per-connection write permissions. If no connection is explicitly marked as default, the first declared connection is used. Credentials are not returned by list_databases, which reports aliases and non-secret connection details instead.

MCP prompts support guided database exploration, query construction, performance analysis, and schema documentation. MCP resources expose browsable schema, table, and database information through postgres:// resource URIs.

Setup and configuration

The TypeScript implementation can be run with npx @javiagui/postgresql-mcp or installed globally with npm. The Python implementation is installed with pipx install postgresql-mcp and runs as postgresql-mcp. Configuration examples are provided for Claude Code and Cursor, and the README states compatibility with Claude Desktop and other MCP clients.

For a basic connection, POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB are required. POSTGRES_HOST defaults to localhost, POSTGRES_PORT defaults to 5432, and POSTGRES_SSLMODE defaults to prefer. ALLOW_WRITE_OPERATIONS defaults to false. QUERY_TIMEOUT defaults to 30 seconds, and MAX_ROWS defaults to 1,000 returned rows.

POSTGRES_CONNECTIONS and the individual POSTGRES_* settings are mutually exclusive. Connection entries can use discrete fields or a PostgreSQL URL, with discrete fields taking precedence when both are present.

Tools and capabilities

JaviMaligno/postgres_mcp MCP server exposes tools for:

• Executing read-only queries and, when permitted, write statements.
• Producing EXPLAIN plans for query optimization.
• Listing schemas, tables, views, functions, and procedures.
• Describing table columns, types, constraints, and view definitions.
• Finding indexes and constraints such as primary keys, foreign keys, unique constraints, and checks.
• Reporting table row counts, size, and bloat statistics.
• Searching for column names across tables.
• Returning PostgreSQL version and connection information.
• Listing configured database aliases without exposing credentials.

Limitations and notes

Write operations are disabled by default and must be enabled explicitly. The server enforces query limits through the configured timeout and maximum-row settings. Connection credentials must remain in the environment; callers cannot supply a host, user, password, or connection string through a tool argument. The README identifies MIT as the project license.