Claude Code PostgreSQL MCP Server Setup

Overview

This page explains how to set up the PostgreSQL MCP Server with Claude Code. This allows Claude Code to directly query and interact with your PostgreSQL database.

Package: mcp-server-postgres (via npx or global install)
Transport: Stdio
Scope: Project-specific (configured per project in ~/.claude.json)

Prerequisites

Node.js installed (required to run the MCP server)
PostgreSQL database accessible from your machine
Database credentials (host, port, username, password, database name)

Installation

Step 1: Install the MCP Server Package

# Option 1: Global install
npm install -g mcp-server-postgres

# Option 2: Use npx (no install needed)
npx mcp-server-postgres

Step 2: Add MCP Server via Claude Code CLI

# Project scope (recommended for database connections)
claude mcp add --scope project --transport stdio postgres-server \
  -- mcp-server-postgres "postgresql://USER:PASSWORD@HOST:PORT/DATABASE"

# Example with real values:
claude mcp add --scope project --transport stdio postgres-server \
  -- mcp-server-postgres "postgresql://postgres:mypassword@192.168.1.199:5432/adventuretube"

Step 3: Verify the Connection

# Inside Claude Code, check MCP status
/mcp

# Expected output:
# ✔ postgres-server - connected

Manual Configuration in ~/.claude.json

If you prefer to configure manually, add the server under your project’s mcpServers section:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "postgres-server": {
          "type": "stdio",
          "command": "mcp-server-postgres",
          "args": [
            "postgresql://USER:PASSWORD@HOST:PORT/DATABASE"
          ],
          "env": {}
        }
      }
    }
  }
}

Configuration Breakdown

Field	Value	Description
`type`	`stdio`	Runs as a local process communicating via stdin/stdout
`command`	`mcp-server-postgres`	The MCP server binary (must be installed globally or available in PATH)
`args`	`["postgresql://..."]`	PostgreSQL connection string as the first argument
`env`	`{}`	Optional environment variables (none needed for basic setup)

Connection String Format

postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE

Component	Example	Description
USERNAME	`postgres`	Database user
PASSWORD	`mypassword`	Database password
HOST	`192.168.1.199` or `localhost`	Database server address
PORT	`5432`	PostgreSQL port (default: 5432)
DATABASE	`adventuretube`	Target database name

Available Tools (After Connection)

Once connected, Claude Code gains access to these database operations:

query – Execute read-only SQL queries against the database
list_tables – List all tables in the database
describe_table – Get schema information for a specific table

Why Project Scope?

Unlike tools like Notion or WordPress that you use across all projects, a database connection is typically project-specific:

Different projects use different databases
Connection credentials vary per project
Database schemas are project-dependent

This is why the Postgres MCP is configured under projects → "/path/to/project" in ~/.claude.json, rather than at the top-level mcpServers (user scope).

Enable/Disable the Server

The server can be toggled without removing the configuration. In ~/.claude.json, the disabledMcpServers array controls which servers are disabled:

"disabledMcpServers": [
  "postgres-server"
]

To re-enable, simply remove "postgres-server" from this array, or use the /mcp command in Claude Code to manage server status.

Troubleshooting

Connection Refused

Verify the database host is reachable from your machine
Check if PostgreSQL is running on the specified port
Ensure the database allows remote connections (check pg_hba.conf)

Authentication Failed

Double-check username and password in the connection string
Verify the user has access to the specified database
Check if the database requires SSL (add ?sslmode=require to the connection string)

MCP Server Not Found

# Install the server globally
npm install -g mcp-server-postgres

# Or verify it's installed
which mcp-server-postgres

Server Shows as Disabled

Check ~/.claude.json for the disabledMcpServers array and remove "postgres-server" from it.

Security Notes

Important: The database password is stored in plain text in ~/.claude.json. Make sure this file has appropriate permissions and is not committed to version control.

Use a dedicated database user with minimal required permissions (read-only if possible)
Avoid using the postgres superuser in production
Consider using environment variables for sensitive credentials
Keep ~/.claude.json out of version control