Skip to main content
Glama
hovecapital

PostgreSQL MCP Server

by hovecapital
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

PostgreSQL MCP Server

MCP Registry npm version

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 with query validation (only SELECT statements allowed)

  • Easy integration with Claude Desktop and Claude Code

  • JSON formatted query results

  • Environment-based default configuration with runtime override support

Related MCP server: Enterprise PostgreSQL MCP Server

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

Variable

Description

Default

DB_HOST

PostgreSQL server hostname

localhost

DB_PORT

PostgreSQL server port

5432

DB_DATABASE

Database name

postgres

DB_USERNAME

PostgreSQL username

postgres

DB_PASSWORD

PostgreSQL password

(empty)

DB_SSL

Enable SSL connection

false

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.

Parameters:

Parameter

Type

Required

Description

connectionString

string

Yes

PostgreSQL connection string

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:

Parameter

Type

Required

Description

sql

string

Yes

SQL query to execute (SELECT only)

connectionString

string

No

Override connection for this query only

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):

    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:

    User: "Connect to postgres://user:pass@newhost/newdb and show me the users table"
Claude: [Uses connect tool first, then query tool]

  3. One-off query to a different database (without switching active connection):

    User: "How many records are in the orders table on postgres://user:pass@analytics/warehouse?"
Claude: [Uses query tool with connectionString parameter]

  4. Revert to default connection:

    User: "Go back to my local database"
Claude: [Uses disconnect tool]

Usage

  1. Restart Claude Desktop/Code after updating the configuration

  2. Start chatting with Claude about your database

Example Queries

Basic queries (uses default/active connection):

"Show me all tables in my database"
"What's the structure of the users table?"
"Get the first 10 records from the products table"
"How many orders were placed last month?"
"Show me users with email addresses ending in @gmail.com"

Dynamic connection examples:

"Connect to postgres://analyst:password@analytics.example.com:5432/warehouse"
"Now show me all the tables"
"What's the total revenue in the sales table?"
"Disconnect and go back to my local database"

One-off queries to different databases:

"Run SELECT count(*) FROM users on postgres://admin:secret@prod.example.com/app"
"Check the orders table on my staging database: postgres://dev:dev@staging/app"

Claude will automatically convert your natural language requests into appropriate SQL queries and execute them against your database.

Security Features

Read-Only Operations

The server enforces read-only access on all connections (both environment-configured and runtime dynamic connections). A query is rejected if it begins with any of the following statement keywords:

  • Data manipulation - INSERT, UPDATE, DELETE, TRUNCATE, COPY, MERGE

  • Schema / DDL - CREATE, ALTER, DROP, COMMENT, RENAME, REASSIGN

  • Permissions - GRANT, REVOKE, SECURITY

  • Session / config - SET, RESET, DISCARD, LOAD

  • Procedures / dynamic execution - CALL, DO, EXECUTE, PREPARE, DEALLOCATE

  • Cursors - DECLARE, FETCH, MOVE, CLOSE

  • Transaction control - BEGIN, START, COMMIT, ROLLBACK, SAVEPOINT, RELEASE, LOCK

  • Maintenance - VACUUM, ANALYZE, REINDEX, CLUSTER, REFRESH, CHECKPOINT

  • Async notification - NOTIFY, LISTEN, UNLISTEN

Only statements beginning with read verbs (e.g. SELECT, WITH, EXPLAIN, SHOW, TABLE, VALUES) are allowed through. Because EXPLAIN ANALYZE executes the statement it wraps, its inner statement is validated too — EXPLAIN ANALYZE DELETE ... is rejected, while EXPLAIN ANALYZE SELECT ... is allowed.

Dynamic Connection Security

When using the connect tool or connectionString parameter:

  • Read-only enforcement still applies - All queries are validated regardless of connection source

  • Credentials are not logged - Connection strings with passwords are never written to logs

  • Sanitized responses - The connect tool response excludes passwords

  • Session-based - Runtime connections only persist for the current MCP session

Recommended Database Setup

For enhanced security, create a dedicated read-only user for the MCP server:

-- Create a read-only user
CREATE USER claude_readonly WITH PASSWORD 'secure_password';

-- Grant only SELECT permissions on your specific schema
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

-- Grant permissions for future tables (optional)
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO claude_readonly;

Troubleshooting

Connection Issues

  1. Verify PostgreSQL is running: Check if your PostgreSQL server is active

  2. Check credentials: Ensure username/password are correct

  3. Network connectivity: Confirm Claude Desktop can reach your PostgreSQL server

Configuration Issues

  1. Restart required: Always restart Claude Desktop after configuration changes

  2. Path accuracy: Ensure the absolute path to dist/index.js is correct

  3. JSON syntax: Validate your claude_desktop_config.json format

Debug Mode

To see server logs, you can run the server manually:

node dist/index.js

File Structure

~/mcp-servers/postgres/
├── src/
│   └── index.ts
├── dist/
│   ├── index.js
│   └── index.d.ts
├── package.json
├── tsconfig.json
└── node_modules/

Dependencies

  • @modelcontextprotocol/sdk: MCP protocol implementation

  • pg: PostgreSQL client for Node.js

Contributing

Feel free to submit issues and enhancement requests!

License

This project is open source and available under the MIT License.

Support

If you encounter issues:

  1. Check the troubleshooting section above

  2. Verify your PostgreSQL connection independently

  3. Ensure Claude Desktop is updated to the latest version

  4. Review the Claude Desktop MCP documentation

Note: This server is designed for development and analysis purposes. For production use, consider additional security measures and monitoring.

Available Tools

3 tools
connectA

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

ParametersJSON Schema
NameRequiredDescriptionDefault
connectionStringYesPostgreSQL connection string (e.g., postgres://user:password@host:5432/database?sslmode=require)

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description reveals that the connection persists until changed or disconnected. However, it does not disclose security implications, error handling, or what happens if already connected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, informative sentences with no unnecessary words. The critical behavioral detail (persistence) is included.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single parameter and no output schema, the description provides all necessary context: what it does, how to use it, and the side effect of persistence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides a detailed description of the connectionString parameter (100% coverage). The tool description adds no additional meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('connect') and the resource ('PostgreSQL database using a connection string'). It distinguishes from sibling tools (disconnect, query) by being the initial setup tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains that the connection persists for subsequent queries, guiding the agent to use this before query operations. It implicitly advises against reconnecting unnecessarily.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

disconnectA

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool disconnects and reverts to the default connection, which is a behavioral change. However, without annotations, it does not elaborate on potential side effects like closing existing queries or impacting other parts of the system.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that conveys all necessary information without any extraneous words. It is efficiently front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema), the description is complete. It explains the action and the result, and the sibling tool names provide additional context for understanding its role.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema description coverage is 100%. No parameter information is needed, and the description adds no extra parameter semantics, which is appropriate. Baseline 4 for zero parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Disconnect', the resource 'current runtime database', and the outcome 'revert to default environment-configured connection'. It distinguishes itself from sibling tools 'connect' (opposite action) and 'query' (different operation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (when you want to disconnect and revert to default), but does not explicitly state when not to use or provide alternative tools. Given the siblings, context is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

queryA

Run a read-only SQL query against the currently connected database

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesSQL query to execute (read-only)
connectionStringNoOptional: PostgreSQL connection string to override the current connection for this query only

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the read-only nature, which is a key behavioral trait. However, with no annotations, it lacks details on error handling, performance implications, or result format. It provides essential but not comprehensive transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that directly states the tool's purpose with no wasted words. It is front-loaded and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with no output schema, the description covers the essential action. It does not explain return values, but this is often inferred for query tools. Slightly lacking in full completeness but adequate given simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds only the global 'read-only' context, not specific parameter semantics beyond what is in the schema. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (run), resource (SQL query), and constraint (read-only, against currently connected database). It distinguishes from sibling tools 'connect' and 'disconnect' by specifying the action is query execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a read-only SQL query needs to be executed. While it doesn't explicitly state when not to use or list alternatives, the context of sibling tools makes it clear this is the query tool. A slight gap in explicit exclusion guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.3.0
    • First observedconnect
    • First observeddisconnect
    • First observedquery
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

Each tool has a distinct purpose: connect establishes a connection, disconnect terminates it, and query runs read-only SQL. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names are single verbs in imperative form (connect, disconnect, query), following a consistent and predictable pattern.

Tool Count4/5

With 3 tools, the server is at the low end of the typical range, but each tool is necessary for basic database interaction (connect, disconnect, query). A slightly larger set could include transaction or metadata tools.

Completeness2/5

The server covers only connectivity and read-only queries, missing write operations (INSERT, UPDATE, DELETE), schema exploration, and transaction management, which are essential for a full PostgreSQL server.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • PostgreSQL MCP Server

    melihbirim
    F
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to interact with PostgreSQL databases using natural language queries, providing secure read-only access to database schemas and SQL translation capabilities.
    6
    13
    -

  • Enterprise PostgreSQL MCP

    kd444
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables secure read-only interactions with PostgreSQL databases through natural language. Provides database inspection, table listing, and SQL query execution with built-in security validation.
    -

  • MCP PostgreSQL Server

    kristofer84
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables secure read-only access to PostgreSQL databases, allowing users to list tables, query schemas, execute SELECT statements, and inspect table structures through natural language interactions.
    751
    4
    MIT

  • PostgreSQL MCP Server

    sebcbi1
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables secure, read-only PostgreSQL database interaction through natural language, with automatic database discovery and connection management.
    2
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hovecapital/read-only-local-postgres-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server