PostgreSQL MCP Server

<!-- mcp-name: io.github.musaddiq-dev/postgresql-mcp-server -->

PostgreSQL MCP Server

A Python Model Context Protocol (MCP) server for inspecting and querying PostgreSQL databases from MCP-compatible clients. It provides schema discovery, safe read-only query execution, query explanation, table previews, index analysis, relationship inspection, and PostgreSQL resources for table metadata.

Features

• List public tables and inspect table schemas
• Execute read-only SQL in a PostgreSQL read-only transaction
• Explain query plans without executing the target query directly
• Preview table rows with a fixed limit
• Inspect foreign-key relationships and indexes
• Expose passive MCP resources for table lists and schema details

Safety Model

postgresqlexecutereadquery runs with PostgreSQL read-only transaction mode, caps returned rows by POSTGRESREADQUERYLIMIT, and rolls back after execution. The server also includes postgresqlexecutewrite_query, which only accepts a single INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, or TRUNCATE statement and can modify data/schema if the connected database user has permission. Do not auto-approve write-capable tools in your MCP client. For public or shared use, run the server with a dedicated read-only PostgreSQL user.

Requirements

• Python 3.11+
• PostgreSQL database
• MCP-compatible client such as Claude Desktop, Cursor, VS Code, or another MCP host

Installation

When published to PyPI, install or run the server like a standard Python MCP package:

uvx mdev-postgresql-mcp-server

For local development from source:

git clone https://github.com/musaddiq-dev/postgresql-mcp-server.git
cd postgresql-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

Copy the example environment file and update it with your database connection details.

cp .env.example .env

Example read-only user:

CREATE USER mcp_readonly WITH PASSWORD 'change-me';
GRANT CONNECT ON DATABASE your_database TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

Running

mdev-postgresql-mcp-server

From a local checkout before PyPI publication, run:

python -m postgresql_mcp_server.server

MCP Client Configuration

For published installs, prefer uvx. MCP servers using stdio must write protocol messages only to stdout; this server writes logs to stderr through Python logging.

Claude Desktop / Cursor / Windsurf / Cline

Most MCP clients accept this mcpServers JSON shape:

{
  "mcpServers": {
    "postgresql": {
      "command": "uvx",
      "args": ["mdev-postgresql-mcp-server"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "mcp_readonly",
        "POSTGRES_PASSWORD": "change-me",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

For local development from this repository, use the installed console script path instead:

Shortened. The full README is on GitHub.