Skip to main content

Getting Started

Welcome to Postgres MCP Server - a Model Context Protocol server for PostgreSQL database operations.

What is Postgres MCP Server?​

Postgres MCP Server enables AI assistants like Claude to interact with PostgreSQL databases through the Model Context Protocol (MCP). It provides a secure, read-only (by default) interface for querying databases, inspecting schemas, and analyzing query performance.

Key Features​

  • 🔒 Secure by Default - Read-only mode prevents accidental data modifications
  • 📄 Smart Pagination - Automatic result limiting with configurable page sizes
  • 🔍 Schema Introspection - Explore tables, views, functions, and constraints
  • ⚡ Query Analysis - EXPLAIN plans and table statistics
  • 🚀 Dual Mode - Works with Claude Desktop (stdio) or as HTTP server (SSE)
  • 🛡️ SQL Validation - AST-based parsing to prevent unsafe queries

Quick Start​

Installation Options​

Install via npx (no installation required):

npx -y @calebmabry/postgres-mcp-server

Or install globally:

npm install -g @calebmabry/postgres-mcp-server

Client Setup​

Postgres MCP Server works with multiple MCP-compatible clients:

  • Claude Desktop - Anthropic's desktop app
  • Cline - VS Code extension for AI-assisted coding
  • Zed - High-performance code editor
  • Docker - Containerized deployment
  • HTTP Server - SSE transport for web clients

Quick Configuration Example​

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@calebmabry/postgres-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "READ_ONLY": "true"
      }
    }
  }
}

Choose your client from the Setup section for detailed configuration instructions.

For Developers​

Install and run as HTTP server:

npm install @calebmabry/postgres-mcp-server
npm run start:http

See HTTP Server Setup for detailed instructions.

Available Tools​

Once configured, you'll have access to these PostgreSQL tools:

  • query - Execute SQL queries with pagination
  • describe_table - Get table structure and column details
  • list_tables - List all tables in a schema
  • list_schemas - List all database schemas
  • list_indexes - List table or schema indexes
  • list_views - List database views
  • list_functions - List functions and procedures
  • get_constraints - Get table constraints (foreign keys, unique, etc.)
  • explain_query - Get query execution plan for performance analysis
  • get_table_stats - Get table statistics (size, row count, etc.)

Next Steps​

Learn More​