Skip to content
Download Longwave

Postgres

Postgres is an MCP server for inspecting PostgreSQL databases. Its connected implementation exposes 9 tools for schema exploration, query analysis and index suggestions.

Add to Longwave Source

Install elsewhere

Install Postgres

Choose a harness. These instructions start the same local MCP server shown on this page.

Claude Code

Run this in your terminal. It adds a user-scoped server; use --scope project instead if it should apply only to the current project.

terminal 
claude mcp add --scope user --transport stdio --env DATABASE_URI=YOUR_DATABASE_URI postgres -- uvx --with 'mcp<2' postgres-mcp

Replace each YOUR_… value with the required secret before running the command.

What it does

Postgres MCP is for database work where the agent needs to see the schema and reason about a query. It gives the agent a database connection instead of a pasted table description.

  • Explore database schemas and tables.
  • Run read-oriented database queries.
  • Explain a slow query.
  • Suggest indexes from query and schema information.
  • Pass the database connection through the server environment.

Available functions

analyze_db_health Analyzes database health. Here are the available health checks: - index - checks for invalid, duplicate, and bloated indexes - connection - checks the number of connection and their utilization - vacuum - checks vacuum health for transaction id wraparound - sequence - checks sequences at risk of exceeding their maximum value - replication - checks replication health including lag and slots - buffer - checks for buffer cache hit rates for indexes and tables - constraint - checks for invalid constraints - all - runs all checks You can optionally specify a single health check or a comma-separated list of health checks. The default is 'all' checks.

Arguments

health_type
string Optional. Valid values are: all, buffer, connection, constraint, index, replication, sequence, vacuum. Default: all
analyze_query_indexes Analyze a list of (up to 10) SQL queries and recommend optimal indexes

Arguments

max_index_size_mb
integer Max index size in MB Default: 10000
method
string Method to use for analysis Allowed values: dta, llm Default: dta
queries required
array List of Query strings to analyze
analyze_workload_indexes Analyze frequently executed queries in the database and recommend optimal indexes

Arguments

max_index_size_mb
integer Max index size in MB Default: 10000
method
string Method to use for analysis Allowed values: dta, llm Default: dta
execute_sql Execute any SQL query

Arguments

sql
string SQL to run Default: all
explain_query Explains the execution plan for a SQL query, showing how the database will execute it and provides detailed cost estimates.

Arguments

analyze
boolean When True, actually runs the query to show real execution statistics instead of estimates. Takes longer but provides more accurate information. Default: false
hypothetical_indexes
array A list of hypothetical indexes to simulate. Each index must be a dictionary with these keys: - 'table': The table name to add the index to (e.g., 'users') - 'columns': List of column names to include in the index (e.g., ['email'] or ['last_name', 'first_name']) - 'using': Optional index method (default: 'btree', other options include 'hash', 'gist', etc.) Examples: [ {"table": "users", "columns": ["email"], "using": "btree"}, {"table": "orders", "columns": ["user_id", "created_at"]} ] If there is no hypothetical index, you can pass an empty list. Default: []
sql required
string SQL query to explain
get_object_details Show detailed information about a database object

Arguments

object_name required
string Object name
object_type
string Object type: 'table', 'view', 'sequence', or 'extension' Default: table
schema_name required
string Schema name
get_top_queries Reports the slowest or most resource-intensive queries using data from the 'pg_stat_statements' extension.

Arguments

limit
integer Number of queries to return when ranking based on mean_time or total_time Default: 10
sort_by
string Ranking criteria: 'total_time' for total execution time or 'mean_time' for mean execution time per call, or 'resources' for resource-intensive queries Default: resources
list_objects List objects in a schema

Arguments

object_type
string Object type: 'table', 'view', 'sequence', or 'extension' Default: table
schema_name required
string Schema name
list_schemas List all schemas in the database

Questions people ask

How do I install a Postgres MCP server?

This catalog entry requires `uv` and a PostgreSQL connection string. Install `uv`, add the server to your MCP client, and provide the connection string through the server environment.

How do I use Postgres MCP in Cursor?

Add the server to Cursor's MCP settings and provide the PostgreSQL connection string securely. Cursor can inspect schemas and run the operations returned by the local process.

Can Postgres MCP run in Python?

The catalog launch uses `uv`, which manages the Python runtime for the server. You do not need to assemble a separate virtual environment if `uv` resolves the package.

Can Postgres MCP run in Docker?

Yes, if the container includes `uv`, can reach PostgreSQL and receives the connection string. Give the server a database role with only the permissions the task needs.

Can Postgres MCP explain a slow query?

Yes. Query explanation is one of the catalog entry's stated uses. The live function schema shows how this version accepts the query and connection context.

Does Postgres MCP change the database?

Do not assume write access. The connected tool list is the source of truth, and the database role should be read-only when the agent only needs inspection.

Can Postgres MCP run read-only queries?

Yes, when the connected database role allows only reads and the server exposes the query operation. Permission comes from PostgreSQL, not from the MCP label.

Let the agent inspect the database before it edits it.

Give it schema, query plans and index evidence instead of a blind SQL prompt.

Download Longwave