mcp-postgresql
A production-oriented MCP server that enables interaction with PostgreSQL databases, providing tools for query execution and schema introspection:
execute_query: Run any SQL statement (SELECT,INSERT,UPDATE,DELETE) and receive result rows or the affected row count.list_tables: Discover all tables in the current database, with an optional filter by schema name.describe_table: Inspect a table's full structure — column names, data types, nullability, default values, and primary key markers.list_databases: Retrieve all PostgreSQL databases available on the connected server.get_table_indexes: View all indexes on a specific table, including their definitions and uniqueness/primary key flags.get_foreign_keys: Discover all foreign key constraints on a table, including referenced target tables and columns.
Provides tools to execute SQL queries, list tables, describe table schemas, list databases, get table indexes, and foreign keys for a PostgreSQL database.
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., "@mcp-postgresql list all tables in the public schema"
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.
MCP Server for PostgreSQL
Production-oriented MCP server for PostgreSQL, exposing database operations to MCP clients (Claude Desktop, VS Code Copilot, Cursor, and compatible hosts).
Features
Query execution (
SELECT,INSERT,UPDATE,DELETE)Database discovery and schema introspection
Table metadata inspection (columns, types, nullability, defaults, PK)
Index and foreign key discovery
Environment-driven configuration for secure deployment
Related MCP server: Azure Database for PostgreSQL MCP Server
Available Tools
Tool | Description |
| Executes a SQL statement and returns rows or affected row count |
| Lists tables from |
| Returns table column metadata and primary key markers |
| Lists all PostgreSQL databases |
| Lists table indexes with definitions and PK/unique flags |
| Lists table foreign keys and referenced targets |
Requirements
Node.js 18+
Access to a PostgreSQL instance
Network connectivity from MCP host to PostgreSQL (
host:port)
Configuration
Set connection settings using environment variables:
Variable | Required | Default | Description |
| No |
| PostgreSQL host or IP |
| No |
| PostgreSQL TCP port |
| No |
| Default database |
| Yes | — | Database user |
| Yes | — | Database password |
| No |
| Enables SSL/TLS |
| No |
| Max pool connections |
| No |
| Pool idle timeout (ms) |
| No |
| Transport mode: |
| No |
| Port for the HTTP server (only used when |
| No |
| Bind address for the HTTP server (only used when |
Usage
Run directly from GitHub
npx github:ferronicardoso/mcp-postgresqlClaude Code (CLI)
claude mcp add postgresql --scope user -- npx -y github:ferronicardoso/mcp-postgresql--scope controls where the server registration is stored:
Scope | Stored in | Visible to |
| project-local, untracked | only you, only in this project |
|
| anyone who clones the repo (commit it to share) |
| your global Claude Code config | you, across every project |
Environment variables can be passed with repeated --env KEY=VALUE flags before the --, e.g.:
Bash (Linux/macOS/WSL):
claude mcp add postgresql --scope user \
--env PGHOST=localhost \
--env PGPORT=5432 \
--env PGDATABASE=postgres \
--env PGUSER=postgres \
--env PGPASSWORD=your-password \
-- npx -y github:ferronicardoso/mcp-postgresqlPowerShell:
claude mcp add postgresql --scope user `
--env PGHOST=localhost `
--env PGPORT=5432 `
--env PGDATABASE=postgres `
--env PGUSER=postgres `
--env PGPASSWORD=your-password `
-- npx -y github:ferronicardoso/mcp-postgresqlCodex CLI
Bash (Linux/macOS/WSL):
codex mcp add postgresql \
--env PGHOST=localhost \
--env PGPORT=5432 \
--env PGDATABASE=postgres \
--env PGUSER=postgres \
--env PGPASSWORD=your-password \
npx -- -y github:ferronicardoso/mcp-postgresqlPowerShell:
codex mcp add postgresql `
--env PGHOST=localhost `
--env PGPORT=5432 `
--env PGDATABASE=postgres `
--env PGUSER=postgres `
--env PGPASSWORD=your-password `
npx -- -y github:ferronicardoso/mcp-postgresqlThis registers the server in ~/.codex/config.toml. To remove it, run codex mcp remove postgresql.
Claude Desktop configuration
%APPDATA%\\Claude\\claude_desktop_config.json:
{
"mcpServers": {
"postgresql": {
"command": "npx",
"args": ["github:ferronicardoso/mcp-postgresql"],
"env": {
"PGHOST": "localhost",
"PGPORT": "5432",
"PGDATABASE": "postgres",
"PGUSER": "postgres",
"PGPASSWORD": "your-password"
}
}
}
}VS Code MCP configuration
.vscode/mcp.json:
{
"servers": {
"postgresql": {
"command": "npx",
"args": ["github:ferronicardoso/mcp-postgresql"],
"env": {
"PGHOST": "localhost",
"PGPORT": "5432",
"PGDATABASE": "postgres",
"PGUSER": "postgres",
"PGPASSWORD": "your-password"
}
}
}
}Run with Docker (HTTP transport)
The published image runs in Streamable HTTP mode by default, for use as a remote MCP endpoint (e.g. from n8n's MCP Client Tool node or any Streamable HTTP-compatible client):
Bash (Linux/macOS/WSL):
docker run -d --name mcp-postgresql \
-p 3002:3002 \
-e PGHOST=host.docker.internal \
-e PGPORT=5432 \
-e PGDATABASE=postgres \
-e PGUSER=postgres \
-e PGPASSWORD=your-password \
ghcr.io/ferronicardoso/mcp-postgresql:latestPowerShell:
docker run -d --name mcp-postgresql `
-p 3002:3002 `
-e PGHOST=host.docker.internal `
-e PGPORT=5432 `
-e PGDATABASE=postgres `
-e PGUSER=postgres `
-e PGPASSWORD=your-password `
ghcr.io/ferronicardoso/mcp-postgresql:latestThe MCP endpoint is then available at http://localhost:3002/mcp.
Local Development
git clone https://github.com/ferronicardoso/mcp-postgresql
cd mcp-postgresql
npm install
npm run buildStart the compiled server:
npm startBuild and Commit Workflow
This repository intentionally tracks dist/ to support npx github:user/repo usage.
The project uses a Husky pre-commit hook to:
build TypeScript (
npm run build)stage generated artifacts (
git add dist)
Manual fallback:
npm run build
git add distSecurity Notes
Never commit real credentials or
.envfiles.Prefer least-privilege database users for production use.
For public or untrusted networks, enable encryption (
PGSSL=true) and configure certificates appropriately.
License
MIT © Raphael Augusto Ferroni Cardoso
Available Tools
6 toolsdescribe_tableA
Returns table structure: columns, types, nullability, defaults, and PK markers.
Inputs: table (required), schema.
execute_queryA
Executes a SQL query in PostgreSQL and returns rows or affected row count.
Inputs: query (required).
get_foreign_keysB
Lists foreign keys of a table and their referenced targets.
Inputs: table (required), schema.
get_table_indexesB
Lists indexes for a table with index definition and PK/uniqueness flags.
Inputs: table (required), schema.
list_databasesA
Lists all PostgreSQL databases in the server.
Inputs: no named parameters.
list_tablesB
Lists tables in the current database, optionally filtered by schema.
Inputs: schema.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct database operation: describe structure, run queries, list foreign keys, list indexes, list databases, and list tables. No overlap in functionality.
All tool names follow a consistent verb_noun pattern with underscores (e.g., describe_table, execute_query). No mixing of conventions.
With 6 tools, the set is well-scoped for a PostgreSQL server, covering essential schema exploration and query execution without being bloated.
Covers core introspection and querying, but lacks tools for DDL operations (create/alter/drop) or listing users/roles. Minor gap for power users.
Maintenance
Related MCP Connectors
Hosted PostgreSQL MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Xata MCP server lets AI agents interact with your Xata projects, and Postgres database branches.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn extensible MCP server for database operations that supports PostgreSQL for managing schemas, tables, data, and user permissions. It features automatic migration recording for DDL changes and integrates with various AI-powered editors like Cursor, Zed, and Claude Code.2MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) Server that allows AI models to securely interact with data hosted in Azure Database for PostgreSQL. It enables natural language querying, schema exploration, and data management through MCP clients like Claude Desktop and Visual Studio Code.MIT
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server for PostgreSQL — built for Claude Desktop, Claude Code, and any MCP-compatible AI agent.Apache 2.0
- AlicenseBqualityCmaintenanceA Model Context Protocol (MCP) server that provides secure database access to PostgreSQL through Kysely ORM, enabling Claude Desktop to interact with PostgreSQL databases using natural language.1015 npm1ISC