Quick Start

Quick Start Guide

Version 1.1.0

Get up and running with PostgreSQL MCP Server in 30 seconds!

---

📋 Prerequisites

Before starting, ensure you have:

1. PostgreSQL Database (version 13-17)

   • Running and accessible instance
   • Valid connection credentials
   • Network connectivity

2. Environment Variable

   export DATABASE_URI="postgresql://username:password@localhost:5432/dbname"

3. MCP Client

   • Claude Desktop, Cursor, or other MCP-compatible client

---

🚀 Installation Options

Option 1: Docker (Recommended)

Pull the latest image:

docker pull neverinfamous/postgres-mcp:latest

Run with environment variable:

docker run -i --rm \
  -e DATABASE_URI="postgresql://username:password@localhost:5432/dbname" \
  neverinfamous/postgres-mcp:latest \
  --access-mode=restricted

Option 2: Python Installation

Install from PyPI:

pip install postgres-mcp

Run the server:

postgres-mcp --access-mode=restricted

Option 3: From Source

Clone the repository:

git clone https://github.com/neverinfamous/postgres-mcp.git
cd postgres-mcp

Install dependencies:

uv sync

Run tests to verify:

uv run pytest -v

---

✅ Verification Steps

1. Test Basic Connectivity

Using your MCP client, try:

mcp_postgres-mcp_list_schemas()

Expected output: List of all database schemas

2. Check Database Health

mcp_postgres-mcp_analyze_db_health(health_type="all")

Expected output: Comprehensive health report

3. Verify Extensions

mcp_postgres-mcp_get_top_queries(sort_by="total_time", limit=5)

Expected output: Top 5 queries (requires pg_stat_statements)

---

🔧 Extension Setup

The server requires some PostgreSQL extensions for full functionality:

Required Extensions

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;  -- Query tracking
CREATE EXTENSION IF NOT EXISTS pg_trgm;             -- Text similarity
CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;       -- Fuzzy matching

Optional Extensions

CREATE EXTENSION IF NOT EXISTS hypopg;    -- Hypothetical indexes
CREATE EXTENSION IF NOT EXISTS vector;    -- Vector similarity (pgvector)
CREATE EXTENSION IF NOT EXISTS postgis;   -- Geospatial operations

Note: Tools gracefully degrade with informative errors if optional extensions are missing.

See Extension Setup for detailed installation instructions.

---

🎯 Next Steps

Now that you're set up, explore:

1. MCP Resources & Prompts - NEW! AI-native intelligence features
2. Core Database Tools - Essential database operations
3. JSON Operations - Work with JSONB data
4. Performance Intelligence - Optimize queries
5. MCP Configuration - Configure your MCP client

---

🛡️ Security Modes

Restricted Mode (Production)

postgres-mcp --access-mode=restricted

• ✅ Read-only operations
• ✅ Advanced SQL validation
• ✅ Query timeout protection
• ✅ Resource usage limits

Unrestricted Mode (Development)

postgres-mcp --access-mode=unrestricted

• ⚠️ Full read/write access
• ✅ Parameter binding protection
• ⚠️ Use only in trusted environments

Recommendation: Always use restricted mode for production databases.

---

📚 Quick Reference

Common Commands

# List all schemas
list_schemas()

# Execute secure SQL
execute_sql(
    sql="SELECT * FROM users WHERE id = %s",
    params=[123]
)

# Explain query plan
explain_query(
    sql="SELECT * FROM orders WHERE customer_id = %s",
    params=[456]
)

# Get database health
analyze_db_health(health_type="all")

# Monitor real-time metrics
monitor_real_time(
    include_queries=True,
    include_locks=True
)

---

🔍 Troubleshooting Quick Fixes

Can't Connect to Database

# Verify PostgreSQL is running
pg_isready -h localhost -p 5432

# Check connection string
echo $DATABASE_URI

Extension Not Found

-- Install missing extension
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Verify installation
SELECT extname, extversion FROM pg_extension;

MCP Server Not Found

• Verify MCP client configuration syntax
• Check that DATABASE_URI is set correctly
• Ensure server is running

See Troubleshooting for more solutions.

---

🎉 You're Ready!

You now have PostgreSQL MCP Server running. Explore the tool categories to see what you can do!

---

Need help? Check out the Troubleshooting page or open an issue.