Server facts
Postgres MCP Pro
Project
- Author
- crystaldba
- Repository
- github.com/crystaldba/postgres-mcp
- License
- MIT
- Category
- Databases
Tech
- Runtime / language
- pythonPython
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 3,403
- Last commit
- Data as of
Tags
- Database Health
- Index Tuning
- Postgresql
- Query Optimization
Overview
Postgres MCP Pro is a PostgreSQL integration aimed at both application development and database performance work. It exposes schema and object details so an assistant can understand the database before generating queries. Beyond SQL execution, its tools inspect query plans, identify slow statements, check database health, and recommend indexes. Health analysis covers areas such as cache behavior, connections, vacuum activity, sequence limits, and problematic indexes. Query planning can incorporate hypothetical indexes to assess a possible change before actually creating it.
Access controls distinguish development from more constrained use. Unrestricted mode permits data and schema writes, while restricted mode uses read-only transactions and execution-time limits. The README documents local stdio clients and an SSE service that multiple clients can share. Installation can use Docker or Python, with database credentials required either way; Python users need version 3.12 or newer. Docker is the recommended route in the README because it avoids some environment-specific issues. Fuller workload and index analysis depends on the optional pg_stat_statements and hypopg database extensions, which may need server configuration or additional installation on self-managed Postgres. These prerequisites make the project more than a connection wrapper: its distinguishing features depend on both the MCP process and capabilities available inside the target database.
Install & configure
Requirements
- Python 3.12+ for this launch path
- uv with uvx
- PostgreSQL database access credentials
- An MCP-compatible client
uvx postgres-mcp --access-mode=restrictedThe README supports this restricted replacement for its unrestricted example. pg_stat_statements and hypopg are optional database extensions needed for fuller performance and index analysis. Docker is also documented.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"postgres-mcp": {
"command": "uvx",
"args": [
"postgres-mcp",
"--access-mode=restricted"
],
"env": {
"DATABASE_URI": "<PostgreSQL connection URI with your database credentials>"
}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"postgres-mcp": {
"command": "uvx",
"args": [
"postgres-mcp",
"--access-mode=restricted"
],
"env": {
"DATABASE_URI": "<PostgreSQL connection URI with your database credentials>"
}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"postgres-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"postgres-mcp",
"--access-mode=restricted"
],
"env": {
"DATABASE_URI": "<PostgreSQL connection URI with your database credentials>"
}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"postgres-mcp": {
"command": "uvx",
"args": [
"postgres-mcp",
"--access-mode=restricted"
],
"env": {
"DATABASE_URI": "<PostgreSQL connection URI with your database credentials>"
}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"postgres-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"postgres-mcp",
"--access-mode=restricted"
],
"env": {
"DATABASE_URI": "<PostgreSQL connection URI with your database credentials>"
}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| list_schemas | Discover schemas available in the PostgreSQL instance. |
| list_objects | Inspect tables, views, sequences, and extensions within a schema. |
| get_object_details | Read an object's columns, indexes, constraints, and related structural details. |
| execute_sql | Run SQL statements subject to the configured access restrictions. |
| explain_query | Inspect a query plan and optionally evaluate hypothetical indexes. |
| get_top_queries | Identify slow statements using pg_stat_statements execution statistics. |
| analyze_workload_indexes | Recommend indexes for resource-intensive statements across a workload. |
| analyze_query_indexes | Recommend indexes for a supplied set of up to ten SQL queries. |
| analyze_db_health | Check cache, connections, indexes, constraints, sequences, and vacuum health. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Inspect tables, views, constraints, and indexes before writing SQL.
- Investigate slow queries with execution plans and statistics.
- Evaluate index recommendations against a workload or selected queries.
- Review database health using a restricted read-only connection.
Strengths
- Combines schema exploration with health and performance tooling.
- Supports hypothetical index evaluation.
- Documents restricted access, stdio, and shared SSE operation.
Limitations
- Advanced workload and index analysis needs optional Postgres extensions.
- Unrestricted mode allows data and schema modification.
- Native Python execution requires Python 3.12 or newer.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
