home / mcp / postgresql mcp server

PostgreSQL MCP Server

Enables Claude to query PostgreSQL databases in a read-only, natural language workflow, returning JSON results.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You can run a read-only MCP server that lets Claude interact with PostgreSQL databases using natural language queries. This server validates queries to be read-only, connects to PostgreSQL at runtime, and returns JSON results suitable for Claude workflows.

How to use

You will connect Claude to a PostgreSQL database in a read-only mode and then ask natural language questions. Start by enabling one or more MCP server configurations, then restart Claude to apply the changes. Use the connect tool to explicitly connect to a different database if needed, run read-only queries, or disconnect to revert to the default environment connection. Claude will translate your natural language requests into SQL queries and execute them against the database.

How to install

Prerequisites you need before installing the MCP server:

Step 1: Install the MCP server using the recommended method

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

Step 2: configure environment credentials

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

Alternative: manual JSON configuration for Claude Desktop

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

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

Step 3: add the MCP server entry in Claude Desktop or Code 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"
      }
    }
  }
}

Step 4: test connectivity

Restart Claude Desktop or Claude Code after configuring. Then ask questions like: “What tables are in my database?”.

Additional installation notes

You can also install the MCP server from npm directly or configure a local build path if you install manually. The following methods are described in the setup flow: 1) Install from MCP Registry with an npx command, 2) Manual JSON configuration for Claude Desktop, 3) Install via npm, and 4) Full local installation with a build step for Claude Code. Each approach results in a ready-to-use MCP server that adheres to read-only constraints.

Configuration

The server operates in two major modes: a default environment-based connection and dynamic runtime connections. When you use a dynamic connection (via the connect tool or a connectionString parameter), the read-only policy remains in effect and credentials are not logged. Runtime connections persist only for the current MCP session.

Environment variables you should provide to connect to PostgreSQL include: DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, and optionally DB_SSL to enable SSL. These are used in both the default configuration and any dynamic connections.

Security reminders: ensure you create a dedicated read-only user in PostgreSQL and grant only SELECT permissions on your target schema to minimize risk.

Using the tools to interact with PostgreSQL

The MCP server exposes three core tools for Claude: connect, disconnect, and query. You use these tools to manage your database session, change the active connection, and retrieve data with read-only SQL queries.

Troubleshooting

If you run into issues, verify that PostgreSQL is running, your credentials are correct, and Claude can reach your database over the network. After changing configuration, restart Claude to apply updates. If you need to inspect logs, run the server manually with Node to view runtime output.

Notes on environment and maintenance

This MCP server is intended for development and analysis purposes. For production use, implement additional security measures and monitoring around database access and log handling.

Example queries

Basic queries use the default active connection: Show me all tables in my database, or retrieve a portion of a table. You can also switch to a different database with a dynamic connection then resume querying.

Available tools

connect

Connect to a PostgreSQL database using a connection string. The connection persists for subsequent queries until changed or disconnected.

disconnect

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

query

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