PostgreSQL MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with PostgreSQL databases through natural language queries.

Features

• Execute read-only SQL queries through Claude Desktop or Claude Code
• Dynamic database connections - connect to any PostgreSQL database at runtime
• Built-in security: statement validation plus database-enforced READ ONLY transactions
• Easy integration with Claude Desktop and Claude Code
• JSON formatted query results
• Environment-based default configuration with runtime override support

Quick Start

For Claude Code Users (Recommended - Easiest Method)

claude mcp add postgres -s user -- npx -y @hovecapital/read-only-postgres-mcp-server

Then set your database environment variables:

export DB_HOST=localhost
export DB_PORT=5432
export DB_DATABASE=your_database_name
export DB_USERNAME=your_username
export DB_PASSWORD=your_password

Done! Restart Claude Code and ask: "What tables are in my database?"

For Claude Desktop Users (Manual Configuration)

1. Open your config file:

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

2. Add this configuration:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-postgres-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

3. Save, restart Claude Desktop, and test!

Prerequisites

• Node.js (v16 or higher) - If using mise, update the command path accordingly
• PostgreSQL database server
• Claude Desktop application

Installation

Option 1: Install from MCP Registry (Recommended)

This server is published in the Model Context Protocol Registry as capital.hove/read-only-local-postgres-mcp-server.

Method A: Claude Code CLI (Easiest!)

claude mcp add postgres -s user -- npx -y @hovecapital/read-only-postgres-mcp-server

Then configure your database credentials using environment variables. Restart Claude Code and you're done!

Benefits:

• One command installation
• No manual JSON editing
• Automatic configuration

Method B: Manual JSON Configuration

For Claude Desktop:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-postgres-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

For Claude Code:

Edit ~/.config/claude-code/settings.json (macOS/Linux) or %APPDATA%\claude-code\settings.json (Windows):

{
  "mcp": {
    "servers": {
      "postgres": {
        "command": "npx",
        "args": ["-y", "@hovecapital/read-only-postgres-mcp-server"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "5432",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

Option 2: Install from npm

npm install -g @hovecapital/read-only-postgres-mcp-server

Option 3: Installation with Claude Code

If you're using Claude Code, you can easily install this MCP server:

# Clone the repository
git clone https://github.com/hovecapital/read-only-local-postgres-mcp-server.git
cd read-only-local-postgres-mcp-server

# Install dependencies and build
npm install
npm run build

Then configure Claude Code by adding to your MCP settings.

Option 4: Manual Installation

1. Clone or Download

Save the repository to a directory on your system:

mkdir ~/mcp-servers/postgres
cd ~/mcp-servers/postgres
git clone https://github.com/hovecapital/read-only-local-postgres-mcp-server.git .

2. Install Dependencies

npm install
npm run build

Configuration

Note: If you installed via Option 1 (MCP Registry with npx), you've already configured everything! This section is for users who chose Options 2, 3, or 4 (npm or manual installation).

Claude Code Configuration

If you're using Claude Code with a manual installation, add the PostgreSQL server to your MCP settings:

1. Open your Claude Code settings (typically in ~/.config/claude-code/settings.json on macOS/Linux or %APPDATA%\claude-code\settings.json on Windows)

2. Add the PostgreSQL MCP server configuration:

{
  "mcp": {
    "servers": {
      "postgres": {
        "command": "node",
        "args": ["/absolute/path/to/read-only-local-postgres-mcp-server/dist/index.js"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "5432",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

1. Restart Claude Code for the changes to take effect.

Claude Desktop Configuration

If you're using Claude Desktop with a manual installation, open your Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add the PostgreSQL server configuration:

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/absolute/path/to/read-only-local-postgres-mcp-server/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Using mise for Node.js

If you're using mise for Node.js version management, make sure to use the full path to the Node.js executable in your configuration.

Environment Variables

Tools

This MCP server exposes three tools that Claude can use to interact with PostgreSQL databases.

connect

Connect to a PostgreSQL database using a connection string. The connection persists for subsequent queries until changed or disconnected. The target must be DB_HOST:DB_PORT or listed in DB_ALLOWED_HOSTS.

Parameters:

Connection String Format:

postgres://username:password@host:port/database?sslmode=require
postgresql://username:password@host:port/database

SSL Modes Supported:

• sslmode=require - Require SSL (recommended for remote connections)
• sslmode=verify-full - Require SSL with certificate verification
• No sslmode parameter - No SSL (for local connections)

Example Usage (natural language):

"Connect to postgres://myuser:mypass@db.example.com:5432/production"
"Connect to this database: postgres://admin:secret@localhost/analytics"

Response:

{
  "status": "connected",
  "host": "db.example.com",
  "port": 5432,
  "database": "production",
  "user": "myuser",
  "ssl": true
}

disconnect

Disconnect from the current runtime database and revert to the default environment-configured connection.

Parameters: None

Example Usage (natural language):

"Disconnect from the current database"
"Go back to the default database"

Response:

{
  "status": "disconnected",
  "message": "Reverted to default environment connection",
  "host": "localhost",
  "database": "postgres"
}

query

Run a read-only SQL query against the currently connected database. Optionally override the connection for a single query.

Parameters:

Example Usage (natural language):

"Show me all tables in the database"
"SELECT * FROM users LIMIT 10"
"Run this query on postgres://other:pass@host/db: SELECT count(*) FROM orders"

Response:

[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob", "email": "bob@example.com" }
]

Tool Reference for LLMs

When using this MCP server, Claude can:

1. Query the default database (configured via environment variables):

   Dockerfile

   Copy

   User: "What tables are in my database?"
   Claude: [Uses query tool with SQL: "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"]
   

2. Connect to a different database dynamically: