MCP PostgreSQL MCP Server

$npx @fabriciofs/mcp-postgres
README.md

Query, monitor, and analyze your PostgreSQL databases directly from Claude.

MCP PostgreSQL

A Model Context Protocol (MCP) server for PostgreSQL integration with Claude Code. Query, monitor, and analyze your PostgreSQL databases directly from Claude.

Features

  • Query Execution - Execute SELECT queries with parameterized inputs
  • Schema Exploration - Browse tables, columns, procedures, and indexes
  • Database Monitoring - Track active queries, blocking sessions, wait stats, and connections
  • Performance Analysis - Identify missing indexes, unused indexes, and fragmentation
  • Write Operations - INSERT, UPDATE, DELETE when enabled (READONLY=false)

Installation

Option 1: From npm (recommended)

npx @fabriciofs/mcp-postgres

Option 2: Global installation

npm install -g @fabriciofs/mcp-postgres

Option 3: Clone and build locally

git clone https://github.com/fabriciofs/mcp-postgres.git
cd mcp-postgres
npm install
npm run build

Configuration

Claude Code Integration

Add to your Claude Code MCP settings (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@fabriciofs/mcp-postgres"],
      "env": {
        "SQL_CONNECTION_URL": "postgres://user:password@localhost:5432/database",
        "READONLY": "true"
      }
    }
  }
}

Or with individual connection parameters:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@fabriciofs/mcp-postgres"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "mydb",
        "SQL_USER": "postgres",
        "SQL_PASSWORD": "yourpassword",
        "SQL_PORT": "5432",
        "SQL_SSL": "false",
        "READONLY": "true"
      }
    }
  }
}

Environment Variables

Connection (choose one method)

Method 1: Connection URL

SQL_CONNECTION_URL=postgres://user:password@host:port/database?ssl=false

Method 2: Individual Parameters

SQL_SERVER=localhost
SQL_DATABASE=mydb
SQL_USER=postgres
SQL_PASSWORD=yourpassword
SQL_PORT=5432              # Optional, default: 5432
SQL_SSL=false              # Optional, default: false
Required Settings
Variable Description
READONLY Required. Set to true for read-only mode or false to enable write operations
Optional Settings
Variable Default Description
QUERY_TIMEOUT 30000 Query timeout in milliseconds (max: 120000)
MAX_ROWS 1000 Maximum rows to return (max: 5000)
POOL_MIN 2 Minimum connection pool size
POOL_MAX 10 Maximum connection pool size
LOG_LEVEL info Log level: debug, info, warn, error

Available Tools

Query Tools

Tool Description
sql_execute Execute SELECT queries with parameterized inputs

Schema Tools

Tool Description
schema_list_tables List all tables and views in the database
schema_describe_table Get detailed table information (columns, indexes, foreign keys)
schema_list_columns Search for columns across all tables
schema_list_procedures List stored procedures
schema_list_indexes List indexes with usage statistics

Monitor Tools

Tool Description
monitor_active_queries Monitor currently running queries
monitor_blocking Monitor blocking sessions and lock chains
monitor_wait_stats Monitor wait statistics for performance bottlenecks
monitor_database_size Monitor database size and file usage
monitor_connections Monitor active connections
monitor_performance_counters Monitor PostgreSQL performance metrics

Analysis Tools

Tool Description
analyze_query Analyze query execution plan and statistics
analyze_suggest_indexes Suggest missing indexes based on query patterns
analyze_unused_indexes Find indexes that are not being used
analyze_duplicate_indexes Find duplicate or overlapping indexes
analyze_fragmentation Analyze index fragmentation levels

Tools (17)

sql_executeExecute SELECT queries with parameterized inputs
schema_list_tablesList all tables and views in the database
schema_describe_tableGet detailed table information (columns, indexes, foreign keys)
schema_list_columnsSearch for columns across all tables
schema_list_proceduresList stored procedures
schema_list_indexesList indexes with usage statistics
monitor_active_queriesMonitor currently running queries
monitor_blockingMonitor blocking sessions and lock chains
monitor_wait_statsMonitor wait statistics for performance bottlenecks
monitor_database_sizeMonitor database size and file usage
monitor_connectionsMonitor active connections
monitor_performance_countersMonitor PostgreSQL performance metrics
analyze_queryAnalyze query execution plan and statistics
analyze_suggest_indexesSuggest missing indexes based on query patterns
analyze_unused_indexesFind indexes that are not being used
analyze_duplicate_indexesFind duplicate or overlapping indexes
analyze_fragmentationAnalyze index fragmentation levels

Environment Variables

READONLYrequiredSet to true for read-only mode or false to enable write operations
SQL_CONNECTION_URLPostgres connection string (Method 1)
SQL_SERVERDatabase host (Method 2)
SQL_DATABASEDatabase name (Method 2)
SQL_USERDatabase user (Method 2)
SQL_PASSWORDDatabase password (Method 2)
QUERY_TIMEOUTQuery timeout in milliseconds (max: 120000)
MAX_ROWSMaximum rows to return (max: 5000)

Configuration

claude_desktop_config.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@fabriciofs/mcp-postgres"],
      "env": {
        "SQL_CONNECTION_URL": "postgres://user:password@localhost:5432/database",
        "READONLY": "true"
      }
    }
  }
}

Try it

→List all tables in my PostgreSQL database.
→Show me the schema and indexes for the 'users' table.
→Are there any active queries currently blocking other sessions?
→Analyze the performance of this query and suggest any missing indexes.
→Find all unused indexes in the database to help optimize storage.

Frequently Asked Questions

What are the key features of MCP PostgreSQL?

Execute SELECT queries with parameterized inputs and configurable row limits.. Explore database schema including tables, columns, procedures, and indexes.. Monitor database health with tools for active queries, blocking sessions, and wait stats.. Perform deep performance analysis to identify missing, unused, or duplicate indexes.. Optional write operations (INSERT, UPDATE, DELETE) via environment configuration..

What can I use MCP PostgreSQL for?

Database Administrators monitoring real-time performance and connection bottlenecks.. Developers exploring unfamiliar database schemas and table relationships via natural language.. Data Analysts running and optimizing complex SQL queries directly from their AI workspace.. DevOps engineers identifying index fragmentation and unused resources to reduce database load..

How do I install MCP PostgreSQL?

Install MCP PostgreSQL by running: npx @fabriciofs/mcp-postgres

What MCP clients work with MCP PostgreSQL?

MCP PostgreSQL works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Use MCP PostgreSQL with Conare

Manage MCP servers visually, upload persistent context, and never start from zero with Claude Code & Codex.

Try Free

Related MCP Servers

Universal DB MCP
Enables Claude Desktop to interact with MySQL, PostgreSQL, and Redis databases
database151 stars
Cube MCP Server
Chat with Cube's AI agent for analytics and data exploration.
database8 stars
CrateDB MCP Server
Connects AI assistants to CrateDB clusters for Text-to-SQL and data analysis.
database8 stars
qmcp
An MCP server for q/kdb+ integration for development and debugging workflows.
database5 stars
Supabase MCP Server
Enables secure interaction with Supabase databases via the PostgREST API
database4 stars
Milvus SDK Code Helper
Retrieves relevant code snippets or documents to help generating pymilvus code.
database2 stars