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

Optional Settings

Available Tools

Query Tools

Schema Tools

Monitor Tools

Analysis Tools

Write Tools (READONLY=false only)

Usage Examples

Once configured, you can ask Claude to interact with your database:

"List all tables in the database"
"Describe the Users table"
"Show me active queries running for more than 5 seconds"
"Find unused indexes in the Orders table"
"Analyze the fragmentation of all indexes"
"What are the top wait statistics?"

Security Considerations

• Always use READONLY=true in production unless write access is explicitly required

• Store credentials securely using environment variables

• Use PostgreSQL roles with minimal required permissions

• Consider network security (VPN, firewall rules) for remote connections

Requirements

• Node.js >= 20.0.0

• PostgreSQL 12 or later

• Appropriate PostgreSQL permissions for the operations you want to perform

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Type check
npm run typecheck

# Run MCP Inspector
npm run inspector

License

MIT License - see LICENSE file for details.