PostgreSQL

This MCP server lets Claude Desktop talk to your local PostgreSQL database using natural language queries. It runs read-only SQL operations, helps you explore schemas, preview data, and returns results in formats suitable for both humans and machines.

How to use

You connect to the PostgreSQL MCP Server from Claude Desktop and start asking it to explore your database, run safe read-only queries, and preview data. You can ask it to list tables, inspect schemas, describe a table’s columns and constraints, or fetch a small sample of rows. Results can be returned as Markdown tables for human reading or as JSON for machine consumption.

How to install

Prerequisites: you need Python 3.10 or higher, a PostgreSQL database (local or remote), and Claude Desktop installed on your machine.

# Create a virtual environment (recommended)
python -m venv venv

# Activate the virtual environment
# On Windows:
venv\Scripts\activate

# On macOS/Linux:
# source venv/bin/activate

# Install required packages
pip install -r requirements.txt

Configure the MCP server on your machine

Prepare environment variables for your PostgreSQL connection and point Claude Desktop to the MCP script. The Windows example shows how to run the server locally using a Python virtual environment.

{
  "mcpServers": {
    "postgres": {
      "command": "C:\\Users\\YourUsername\\postgres-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YourUsername\\postgres-mcp\\postgres_mcp.py"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "your_database_name",
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password"
      }
    }
  }
}

Test the server

Before connecting Claude Desktop, verify the server has no syntax errors and is ready to run.

# Test that the server script has no syntax errors
python -m py_compile postgres_mcp.py

# If no errors are shown, the server is ready

Available tools

postgres_execute_query

Execute a SELECT query and return results in Markdown or JSON.

postgres_list_tables

List all tables in a given schema to understand the database structure.

postgres_describe_table

Describe a table to reveal detailed column information and constraints.

postgres_get_table_sample

Fetch a small sample of rows from a table for quick data preview.