pgsql

Executes health checks, suggests indexes, explains queries, and safely runs SQL against PostgreSQL data.

typescript

0

GitHub Stars

typescript

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "surajmandalcell-pgsql-mcp": {
      "command": "uvx",
      "args": [
        "pgsql-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

pgsql-mcp is a PostgreSQL MCP server that helps you analyze index health, tune queries, review explain plans, and run safe SQL. It empowers you to optimize workload performance with health checks, hypothetical indexes, and read-only safety for production runs.

How to use

You interact with the MCP server through an MCP client, connecting over a local process (stdio) or via an HTTP transport where supported. Start the MCP server with your preferred method, provide a database connection string, and then use the client to list schemas, inspect objects, execute read queries, and request index recommendations or health analyses. You can review query plans, simulate hypothetical indexes, and run health checks to understand index health, connection utilization, buffer cache, and vacuum health.

Typical workflows include: 1) Inspecting your database structure to understand schemas and objects. 2) Running explain plans with or without hypothetical indexes to compare performance. 3) Analyzing and recommending indexes for workload optimization. 4) Executing safe, read-only queries in production when in restricted access mode.

How to install

Prerequisites: you need Docker or a runtime for direct commands and a PostgreSQL connection URI. If you prefer a local runtime, you can run the MCP server with a runtime command or via Docker; both require a DATABASE_URI that points to your PostgreSQL database.

Option A: Run via Docker (recommended for quick starts) - Start the server in stdio mode with a direct container run using your DATABASE_URI.

Option B: Run a local stdio command with uvx or npm-based runtimes - Use a local process launcher and pass the database URI via environment variable.

Option C: Use a cloud IDE integration if you are connecting from Claude Code or other cloud environments, supplying the DATABASE_URI in the environment configuration.

Optional: Postgres Extensions

For full index tuning capabilities, install these extensions on your PostgreSQL database: 1) pg_stat_statements 2) hypopg.

Available tools

list_schemas

List all database schemas.

list_objects

List tables, views, and sequences in a schema.

get_object_details

Get columns, constraints, and indexes for an object.

execute_sql

Execute SQL against the database; in restricted mode this is read-only.

explain_query

Get query execution plans with support for hypothetical indexes.

get_top_queries

Find slowest queries using pg_stat_statements.

analyze_workload_indexes

Recommend indexes for your workload.

analyze_query_indexes

Recommend indexes for specific queries.

analyze_db_health

Run comprehensive health checks across the database.