PostgreSQL MCP Server
This server lets Claude interact with PostgreSQL databases through natural language by exposing MCP tools for connecting, disconnecting, and running read-only queries.
Connect to any allowed PostgreSQL database at runtime using a connection string (persists until changed or disconnected)
Disconnect from the runtime database and revert to the default environment-configured connection
Run read-only SQL queries against the current database, with optional per-query connection string override
Query the default database configured via environment variables (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, DB_SSL)
Enforce security through read-only transactions, single-statement validation, denylisted dangerous functions, and host allowlists for dynamic connections
Return JSON-formatted query results for easy analysis
Support SSL modes for remote connections (sslmode=require, verify-full)
Provides tools for connecting to and querying PostgreSQL databases, allowing read-only SQL execution and dynamic connection to any PostgreSQL instance via connection strings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PostgreSQL MCP Server What tables are in my database?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 ONLYtransactionsEasy 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-serverThen 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_passwordDone! 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.json2. 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-serverThen 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-serverOption 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 buildThen 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 buildConfiguration
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:
Open your Claude Code settings (typically in
~/.config/claude-code/settings.jsonon macOS/Linux or%APPDATA%\claude-code\settings.jsonon Windows)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"
}
}
}
}
}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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonAdd 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 |
| PostgreSQL server hostname |
|
| PostgreSQL server port |
|
| Database name |
|
| PostgreSQL username |
|
| PostgreSQL password | (empty) |
| Enable SSL connection |
|
| Comma-separated | (empty) |
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:
Parameter | Type | Required | Description |
| string | Yes | PostgreSQL connection string |
Connection String Format:
postgres://username:password@host:port/database?sslmode=require
postgresql://username:password@host:port/databaseSSL Modes Supported:
sslmode=require- Require SSL (recommended for remote connections)sslmode=verify-full- Require SSL with certificate verificationNo 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 |
| string | Yes | SQL query to execute (SELECT only) |
| 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:
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'"]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]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]Revert to default connection:
User: "Go back to my local database" Claude: [Uses disconnect tool]
Usage
Restart Claude Desktop/Code after updating the configuration
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) in three layers:
Database-enforced read-only transaction. Every query runs inside
BEGIN READ ONLY, and the connection is closed afterwards, so nothing is ever committed. PostgreSQL itself rejectsINSERT,UPDATE,DELETE,MERGE, DDL,SELECT INTO,nextval(), large-object writes and any write hidden in a CTE (WITH x AS (INSERT ...) SELECT ...) or a function body, regardless of how the statement is spelled.Single statement per query. Queries are sent with the extended query protocol, which PostgreSQL restricts to one statement, so
SELECT 1; DROP TABLE ...is rejected by the server.Statement validation before execution. Leading comments are stripped, then a query is rejected if it begins with any of the following statement keywords:
Data manipulation -
INSERT,UPDATE,DELETE,TRUNCATE,COPY,MERGESchema / DDL -
CREATE,ALTER,DROP,COMMENT,RENAME,REASSIGNPermissions -
GRANT,REVOKE,SECURITYSession / config -
SET,RESET,DISCARD,LOADProcedures / dynamic execution -
CALL,DO,EXECUTE,PREPARE,DEALLOCATECursors -
DECLARE,FETCH,MOVE,CLOSETransaction control -
BEGIN,START,COMMIT,ROLLBACK,SAVEPOINT,RELEASE,LOCKMaintenance -
VACUUM,ANALYZE,REINDEX,CLUSTER,REFRESH,CHECKPOINTAsync 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.
A read-only transaction does not stop functions that touch the server filesystem, run arbitrary SQL, or change process state, so a query is also rejected if it mentions any of these anywhere in its text: pg_read_file, pg_read_binary_file, pg_stat_file, pg_ls_*, pg_file_*, pg_logdir_ls, pg_logfile_rotate, lo_import, lo_export, dblink*, query_to_xml*, crosstab*, connectby, set_config, pg_terminate_backend, pg_cancel_backend, pg_reload_conf, pg_rotate_logfile, pg_sleep*. Unicode-escaped identifiers (U&"...") are rejected because they could spell one of these names another way.
Function-name matching is a denylist and cannot be complete. The dedicated read-only role below removes the underlying privileges (pg_write_server_files, pg_read_server_files, superuser) that file operations need, and is the recommended setup.
Dynamic Connection Security
When using the connect tool or connectionString parameter:
Host allowlist - Runtime connection strings may only target
DB_HOST:DB_PORTor ahost:portpair listed inDB_ALLOWED_HOSTS. Other targets are rejected before any socket is opened, so the tools cannot be used to scan ports on the host or its network.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
connecttool response excludes passwordsSession-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
Verify PostgreSQL is running: Check if your PostgreSQL server is active
Check credentials: Ensure username/password are correct
Network connectivity: Confirm Claude Desktop can reach your PostgreSQL server
Configuration Issues
Restart required: Always restart Claude Desktop after configuration changes
Path accuracy: Ensure the absolute path to
dist/index.jsis correctJSON syntax: Validate your
claude_desktop_config.jsonformat
Debug Mode
To see server logs, you can run the server manually:
node dist/index.jsFile 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:
Check the troubleshooting section above
Verify your PostgreSQL connection independently
Ensure Claude Desktop is updated to the latest version
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 toolsconnectA
Connect to a PostgreSQL database using a connection string. The connection persists for subsequent queries until changed or disconnected. Only hosts listed in DB_ALLOWED_HOSTS (plus the default DB_HOST:DB_PORT) are permitted.
Inputs: connectionString (required).
disconnectA
Disconnect from the current runtime database and revert to the default environment-configured connection
Inputs: no named parameters.
queryA
Run a read-only SQL query against the currently connected database
Inputs: sql (required), connectionString.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools have completely distinct roles: connect establishes a connection, disconnect tears it down, and query executes SQL. There is no overlap or ambiguity between them.
All tool names are single lowercase verbs in the imperative style: connect, disconnect, query. The naming pattern is perfectly consistent and predictable.
Three tools is an appropriate scope for a focused read-only query server: connection management plus query execution. Each tool has a clear, necessary purpose.
The connection lifecycle is complete, and query covers the core read-only use case. Missing conveniences like schema listing or write operations are either outside the stated read-only scope or can be worked around via SQL queries.
Maintenance
Related MCP Connectors
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query, explore, and manage your databases through natural conversation.
Query your Postgres from ChatGPT or Claude without exposing the database or handing over credentials. Run npx boltschema connect next to your database and it dials out over HTTPS — no inbound firewall rule, no open port, works with localhost and VPC-private databases. Read-only is enforced by a SQL guard, a Postgres READ ONLY transaction, and a scoped role generated for you.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with PostgreSQL databases using natural language queries, providing secure read-only access to database schemas and SQL translation capabilities.6ISC
- -licenseNot gradedqualityNot gradedmaintenanceEnables secure read-only interactions with PostgreSQL databases through natural language. Provides database inspection, table listing, and SQL query execution with built-in security validation.-
- AlicenseNot gradedqualityBmaintenanceEnables 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.650 npm4MIT
- AlicenseNot gradedqualityDmaintenanceEnables secure, read-only PostgreSQL database interaction through natural language, with automatic database discovery and connection management.2MIT