PostgreSQL

by crystaldba

113 stars

1.2k downloads

Not rated

GitHub

About

Helps you and your AI agents throughout the entire development process—from writing SQL to tuning performance safely.

Details

Author: crystaldba
Repository: crystaldba/postgres-mcp
GitHub stars: 113
Downloads: 1,205
License: MIT License
Categories: Database, Other, Infrastructure, AI, Design, Developer Tools, Search, Frontend, API

- Database health monitoring (index health, connections, buffer cache, replication lag, etc.)
- Index tuning using workload analysis and industrial-strength algorithms
- Query plan validation and hypothetical index simulation
- Schema intelligence for context-aware SQL generation
- Safe SQL execution with read-only and restricted access modes
- Support for both stdio and SSE MCP transports

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name PostgreSQL

Command (node, npx, python, etc.) docker
Arguments
- Argument 1 run
- Argument 2 -i
- Argument 3 --rm
- Argument 4 -e
- Argument 5 DATABASE_URI
- Argument 6 crystaldba/postgres-mcp
- Argument 7 --access-mode=unrestricted
Environment
- DATABASE_URI postgresql://username:password@localhost:5432/dbname
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

From the repository

Install Postgres Mcp via Docker (docker pull crystaldba/postgres-mcp) or Python (pipx install postgres-mcp or uv pip install postgres-mcp). Configure your MCP client (e.g., Claude Desktop, Cursor) by editing the mcpServers configuration with a DATABASE_URI and optionally the --access-mode flag (unrestricted or restricted). For full index tuning and performance analysis, optionally install the pg_stat_statements and hypopg Postgres extensions.

`list_schemas`

Lists all database schemas available in the PostgreSQL instance.

`list_objects`

Lists database objects (tables, views, sequences, extensions) within a specified schema.

`get_object_details`

Provides information about a specific database object, for example, a table's columns, constraints, and indexes.

`execute_sql`

Executes SQL statements on the database, with read-only limitations when connected in restricted mode.

`explain_query`

Gets the execution plan for a SQL query describing how PostgreSQL will process it and exposing the query planner's cost model. Can be invoked with hypothetical indexes to simulate the behavior after adding indexes.

`get_top_queries`

Reports the slowest SQL queries based on total execution time using pg_stat_statements data.

`analyze_workload_indexes`

Analyzes the database workload to identify resource-intensive queries, then recommends optimal indexes for them.

`analyze_query_indexes`

Analyzes a list of specific SQL queries (up to 10) and recommends optimal indexes for them.

`analyze_db_health`

Performs comprehensive health checks including: buffer cache hit rates, connection health, constraint validation, index health (duplicate/unused/invalid), sequence limits, and vacuum health.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "postgresql": {
            "env": {
                "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
            },
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URI",
                "crystaldba/postgres-mcp",
                "--access-mode=unrestricted"
            ],
            "command": "docker"
        }
    }
}

Linux

{
    "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
    },
    "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
    ],
    "command": "docker"
}

Macos

{
    "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
    },
    "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
    ],
    "command": "docker"
}

Windows

{
    "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
    },
    "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
    ],
    "command": "docker"
}

A Postgres MCP server with index tuning, explain plans, health checks, and safe sql execution.

Postgres MCP Prois an open source Model Context Protocol (MCP) server built to support you and your AI agents throughout theentire development process—from initial coding, through testing and deployment, and to production tuning and maintenance.

Postgres MCP Pro does much more than wrap a database connection.

- 🔍 Database Health- analyze index health, connection utilization, buffer cache, vacuum health, sequence limits, replication lag, and more.
- ⚡ Index Tuning- explore thousands of possible indexes to find the best solution for your workload, using industrial-strength algorithms.
- 📈 Query Plans- validate and optimize performance by reviewing EXPLAIN plans and simulating the impact of hypothetical indexes.
- 🧠 Schema Intelligence- context-aware SQL generation based on detailed understanding of the database schema.
- 🛡️ Safe SQL Execution- configurable access control, including support for read-only mode and safe SQL parsing, making it usable for both development and production.

Postgres MCP Pro supports both theStandard Input/Output (stdio)and Server-Sent Events (SSE)transports, for flexibility in different environments.

For additional background on why we built Postgres MCP Pro, see our launch blog post.

- Challenge:We generated a movie app using an AI assistant, but the SQLAlchemy ORM code ran painfully slow.
- Solution:Using Postgres MCP Pro with Cursor, we fixed the performance issues in minutes.

- 🚀 Fixed performance - including ORM queries, indexing, and caching
- 🛠️ Fixed a broken page - by prompting the agent to explore the data, fix queries, and add related content.
- 🧠 Improved the top movies - by exploring the data and fixing the ORM query to surface more relevant results.

See the video below or read the play-by-play.

https://github.com/user-attachments/assets/24e05745-65e9-4998-b877-a368f1eadc13

Before getting started, ensure you have:
- Access credentials for your database.
- DockerorPython 3.12 or higher.

You can confirm your access credentials are valid by usingpsqlor a GUI tool such as pgAdmin.

The choice to use Docker or Python is yours. We generally recommend Docker because Python users can encounter more environment-specific issues. However, it often makes sense to use whichever method you are most familiar with.

Choose one of the following methods to install Postgres MCP Pro:

Pull the Postgres MCP Pro MCP server Docker image. This image contains all necessary dependencies, providing a reliable way to run Postgres MCP Pro in a variety of environments.

If you havepipxinstalled you can install Postgres MCP Pro with:

Otherwise, install Postgres MCP Pro withuv:

If you need to installuv, see the uv installation instructions.

We provide full instructions for configuring Postgres MCP Pro with Claude Desktop. Many MCP clients have similar configuration files, you can adapt these steps to work with the client of your choice.

You will need to edit the Claude Desktop configuration file to add Postgres MCP Pro. The location of this file depends on your operating system:

- MacOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%APPDATA%/Claude/claude_desktop_config.json

You can also useSettingsmenu item in Claude Desktop to locate the configuration file.

You will now edit themcpServerssection of the configuration file.

{ "mcpServers": { "postgres": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "DATABASE_URI", "crystaldba/postgres-mcp", "--access-mode=unrestricted" ], "env": { "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname" } } } }

The Postgres MCP Pro Docker image will automatically remap the hostnamelocalhostto work from inside of the container.

- MacOS/Windows: Useshost.docker.internalautomatically
- Linux: Uses172.17.0.1or the appropriate host address automatically

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

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

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

Replacepostgresql://...with yourPostgres database connection URI.

Postgres MCP Pro supports multipleaccess modesto give you control over the operations that the AI agent can perform on the database:

- Unrestricted Mode: Allows full read/write access to modify data and schema. It is suitable for development environments.
- Restricted Mode: Limits operations to read-only transactions and imposes constraints on resource utilization (presently only execution time). It is suitable for production environments.

To use restricted mode, replace--access-mode=unrestrictedwith--access-mode=restrictedin the configuration examples above.

Many MCP clients have similar configuration files to Claude Desktop, and you can adapt the examples above to work with the client of your choice.

- If you are using Cursor, you can use navigate from theCommand PalettetoCursor Settings, then open theMCPtab to access the configuration file.
- If you are using Windsurf, you can navigate to from theCommand PalettetoOpen Windsurf Settings Pageto access the configuration file.
- If you are using Goose rungoose configure, then selectAdd Extension.
- If you are using Qodo Gen, open the Chat panel, clickConnect more tools, click+ Add new MCP, then add the new configuration.

Postgres MCP Pro supports the[SSE transport, which allows multiple MCP clients to share one server, possibly a remote server. To use the SSE transport, you need to start the server with the--transport=sseoption.

docker run -p 8000:8000 \ -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \ crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

Then update your MCP client configuration to call the the MCP server. For example, in Cursor'smcp.jsonor Cline'scline_mcp_settings.jsonyou can put:

{ "mcpServers": { "postgres": { "type": "sse", "url": "http://localhost:8000/sse" } } }

For Windsurf, the format inmcp_config.jsonis slightly different:

{ "mcpServers": { "postgres": { "type": "sse", "serverUrl": "http://localhost:8000/sse" } } }

Postgres Extension Installation (Optional)

To enable index tuning and comprehensive performance analysis you need to load thepg_stat_statementsandhypopgextensions on your database.

- Thepg_stat_statementsextension allows Postgres MCP Pro to analyze query execution statistics. For example, this allows it to understand which queries are running slow or consuming significant resources.
- Thehypopgextension allows Postgres MCP Pro to simulate the behavior of the Postgres query planner after adding indexes.

Installing extensions on AWS RDS, Azure SQL, or Google Cloud SQL

…

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

list_schemas

list_objects

get_object_details

execute_sql

explain_query

get_top_queries

analyze_workload_indexes

analyze_query_indexes

analyze_db_health

Claude Desktop / Cursor

Linux

Macos

Windows

A Postgres MCP server with index tuning, explain plans, health checks, and safe sql execution.

Postgres Extension Installation (Optional)

Installing extensions on AWS RDS, Azure SQL, or Google Cloud SQL

Install

More like this

Sequential Thinking

Redis

Filesystem

EverArt

Google Drive

Sqlite

`list_schemas`

`list_objects`

`get_object_details`

`execute_sql`

`explain_query`

`get_top_queries`

`analyze_workload_indexes`

`analyze_query_indexes`

`analyze_db_health`