PostgreSQL MCP server
✓ VerifiedAllows an AI client to inspect schemas, execute read-only queries, and analyze indexes within a PostgreSQL database.
Also known as musaddiq-dev/postgresql-mcp-server, postgresql-mcp-server, mdev-postgresql-mcp-server
- Stars
- 1
- Tools
- 10
- Downloads, 30 days
- 3,692
- Latest version
- 0.1.2
- Last commit
- May 23, 2026
- License
- MIT
What is PostgreSQL MCP?
PostgreSQL allows an AI client to inspect schemas, execute read-only queries, and analyze indexes within a PostgreSQL database. It exposes 10 tools, such as postgresql_list_tables, postgresql_describe_table, postgresql_execute_read_query.
Summary generated from the project's README
About PostgreSQL MCP server
Interacting with PostgreSQL databases through an AI client is what this server enables for developers and database administrators. It allows an AI to perform schema discovery, inspect foreign-key relationships, and analyze indexes or table sizes. By connecting to a PostgreSQL instance via environment variables like host, port, and database name, users can use tools such as postgresql_list_tables and postgresql_describe_table to understand their data structures.
Safety is a primary focus, as the postgresql_execute_read_query tool runs within a read-only transaction and rolls back after execution. This tool also respects a POSTGRES_READ_QUERY_LIMIT to prevent overwhelming the client. While a postgresql_execute_write_query tool exists for single modifying statements, it is intended for use with caution and requires explicit approval. The server works with MCP-compatible hosts including Claude Desktop, Cursor, VS Code, and the Claude Code CLI using a stdio transport.
What you can do with it
- 1Explore database structuresAsk the AI to list all public tables and show the columns for a specific table.
- 2Analyze query performanceRequest an explanation of a query plan to understand how a specific SQL statement will execute.
- 3Inspect data relationshipsHave the AI identify how different tables are linked through foreign keys.
- 4Preview table contentsAsk the AI to show a small sample of rows from a table to understand the data format.
Written from the project's README. Every use case is checked against a quote from it.
How to install PostgreSQL MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall PostgreSQL MCP in Claude Code
$ claude mcp add --env 'POSTGRES_DB=<POSTGRES_DB>' --env 'POSTGRES_HOST=<POSTGRES_HOST>' --env 'POSTGRES_PORT=<POSTGRES_PORT>' --env 'POSTGRES_USER=<POSTGRES_USER>' --env 'POSTGRES_PASSWORD=<YOUR_POSTGRES_PASSWORD>' postgresql-mcp-server -- uvx mdev-postgresql-mcp-serverInstall PostgreSQL MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"postgresql-mcp-server": {
"command": "uvx",
"args": [
"mdev-postgresql-mcp-server"
],
"env": {
"POSTGRES_DB": "<POSTGRES_DB>",
"POSTGRES_HOST": "<POSTGRES_HOST>",
"POSTGRES_PORT": "<POSTGRES_PORT>",
"POSTGRES_USER": "<POSTGRES_USER>",
"POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
}
}
}
}Install PostgreSQL MCP in VS Code
.vscode/mcp.json
{
"servers": {
"postgresql-mcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"mdev-postgresql-mcp-server"
],
"env": {
"POSTGRES_DB": "<POSTGRES_DB>",
"POSTGRES_HOST": "<POSTGRES_HOST>",
"POSTGRES_PORT": "<POSTGRES_PORT>",
"POSTGRES_USER": "<POSTGRES_USER>",
"POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
}
}
}
}Install PostgreSQL MCP in VS Code CLI
$ code --add-mcp '{"name":"postgresql-mcp-server","type":"stdio","command":"uvx","args":["mdev-postgresql-mcp-server"],"env":{"POSTGRES_DB":"<POSTGRES_DB>","POSTGRES_HOST":"<POSTGRES_HOST>","POSTGRES_PORT":"<POSTGRES_PORT>","POSTGRES_USER":"<POSTGRES_USER>","POSTGRES_PASSWORD":"<YOUR_POSTGRES_PASSWORD>"}}'Install PostgreSQL MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"postgresql-mcp-server": {
"command": "uvx",
"args": [
"mdev-postgresql-mcp-server"
],
"env": {
"POSTGRES_DB": "<POSTGRES_DB>",
"POSTGRES_HOST": "<POSTGRES_HOST>",
"POSTGRES_PORT": "<POSTGRES_PORT>",
"POSTGRES_USER": "<POSTGRES_USER>",
"POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
}
}
}
}Install PostgreSQL MCP in Codex
$ codex mcp add postgresql-mcp-server --env 'POSTGRES_DB=<POSTGRES_DB>' --env 'POSTGRES_HOST=<POSTGRES_HOST>' --env 'POSTGRES_PORT=<POSTGRES_PORT>' --env 'POSTGRES_USER=<POSTGRES_USER>' --env 'POSTGRES_PASSWORD=<YOUR_POSTGRES_PASSWORD>' -- uvx mdev-postgresql-mcp-serverInstall PostgreSQL MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.postgresql-mcp-server] command = "uvx" args = ["mdev-postgresql-mcp-server"] [mcp_servers.postgresql-mcp-server.env] POSTGRES_DB = "<POSTGRES_DB>" POSTGRES_HOST = "<POSTGRES_HOST>" POSTGRES_PORT = "<POSTGRES_PORT>" POSTGRES_USER = "<POSTGRES_USER>" POSTGRES_PASSWORD = "<YOUR_POSTGRES_PASSWORD>"
Install PostgreSQL MCP in Gemini CLI
$ gemini mcp add -s user -e 'POSTGRES_DB=<POSTGRES_DB>' -e 'POSTGRES_HOST=<POSTGRES_HOST>' -e 'POSTGRES_PORT=<POSTGRES_PORT>' -e 'POSTGRES_USER=<POSTGRES_USER>' -e 'POSTGRES_PASSWORD=<YOUR_POSTGRES_PASSWORD>' postgresql-mcp-server uvx -- mdev-postgresql-mcp-serverInstall PostgreSQL MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"postgresql-mcp-server": {
"command": "uvx",
"args": [
"mdev-postgresql-mcp-server"
],
"env": {
"POSTGRES_DB": "<POSTGRES_DB>",
"POSTGRES_HOST": "<POSTGRES_HOST>",
"POSTGRES_PORT": "<POSTGRES_PORT>",
"POSTGRES_USER": "<POSTGRES_USER>",
"POSTGRES_PASSWORD": "<YOUR_POSTGRES_PASSWORD>"
}
}
}
}PostgreSQL MCP tools 10
Detected from the READMEpostgresql_list_tablespostgresql_describe_tablepostgresql_execute_read_querypostgresql_execute_write_querypostgresql_explain_querypostgresql_get_database_summarypostgresql_get_relationshipspostgresql_analyze_indexespostgresql_preview_tablepostgresql_search_sql_definitions
| postgresql_list_tables | — | |
| postgresql_describe_table | — | |
| postgresql_execute_read_query | — | |
| postgresql_execute_write_query | — | |
| postgresql_explain_query | — | |
| postgresql_get_database_summary | — | |
| postgresql_get_relationships | — | |
| postgresql_analyze_indexes | — | |
| postgresql_preview_table | — | |
| postgresql_search_sql_definitions | — |
Configuration
POSTGRES_DBRequiredPostgreSQL database name
POSTGRES_HOSTRequiredPostgreSQL host
POSTGRES_PORTRequiredPostgreSQL port
POSTGRES_USERRequiredPostgreSQL username
POSTGRES_PASSWORDSecretPostgreSQL password
POSTGRES_READ_QUERY_LIMITMaximum rows returned by read queries
| Name | Description | |
|---|---|---|
| POSTGRES_DB | PostgreSQL database name | Required |
| POSTGRES_HOST | PostgreSQL host | Required |
| POSTGRES_PORT | PostgreSQL port | Required |
| POSTGRES_USER | PostgreSQL username | Required |
| POSTGRES_PASSWORD | PostgreSQL password | Secret |
| POSTGRES_READ_QUERY_LIMIT | Maximum rows returned by read queries |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablemusaddiq-dev/postgresql-mcp-server is public and reachablegithub.com/musaddiq-dev/postgresql-mcp-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Sigstore attestation for mdev-postgresql-mcp-serverpypi.org/project/mdev-postgresql-mcp-server/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-05-23github.com/musaddiq-dev/postgresql-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mdev-postgresql-mcp-serverPass
- No critical advisory in the package or its dependencies31 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPostgreSQL MCP Server
A Python Model Context Protocol (MCP) server for inspecting and querying PostgreSQL databases from MCP-compatible clients. It provides schema discovery, safe read-only query execution, query explanation, table previews, index analysis, relationship inspection, and PostgreSQL resources for table metadata.
Features
- List public tables and inspect table schemas
- Execute read-only SQL in a PostgreSQL read-only transaction
- Explain query plans without executing the target query directly
- Preview table rows with a fixed limit
- Inspect foreign-key relationships and indexes
- Expose passive MCP resources for table lists and schema details
Safety Model
postgresql_execute_read_query runs with PostgreSQL read-only transaction mode, caps returned rows by POSTGRES_READ_QUERY_LIMIT, and rolls back after execution. The server also includes postgresql_execute_write_query, which only accepts a single INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, or TRUNCATE statement and can modify data/schema if the connected database user has permission. Do not auto-approve write-capable tools in your MCP client. For public or shared use, run the server with a dedicated read-only PostgreSQL user.
Requirements
- Python 3.11+
- PostgreSQL database
- MCP-compatible client such as Claude Desktop, Cursor, VS Code, or another MCP host
Installation
When published to PyPI, install or run the server like a standard Python MCP package:
uvx mdev-postgresql-mcp-server
For local development from source:
git clone https://github.com/musaddiq-dev/postgresql-mcp-server.git
cd postgresql-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .
Configuration
Copy the example environment file and update it with your database connection details.
cp .env.example .env
| Variable | Description | Required | Default |
|---|---|---|---|
POSTGRES_HOST |
PostgreSQL host | Yes | localhost |
POSTGRES_PORT |
PostgreSQL port | Yes | 5432 |
POSTGRES_USER |
PostgreSQL username | Yes | None |
POSTGRES_PASSWORD |
PostgreSQL password | No | None |
POSTGRES_DB |
PostgreSQL database name | Yes | None |
LOG_LEVEL |
Python logging level written to stderr | No | INFO |
POSTGRES_READ_QUERY_LIMIT |
Maximum rows returned by read queries | No | 1000 |
Example read-only user:
CREATE USER mcp_readonly WITH PASSWORD 'change-me';
GRANT CONNECT ON DATABASE your_database TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;
Running
mdev-postgresql-mcp-server
From a local checkout before PyPI publication, run:
python -m postgresql_mcp_server.server
MCP Client Configuration
For published installs, prefer uvx. MCP servers using stdio must write protocol messages only to stdout; this server writes logs to stderr through Python logging.
Claude Desktop / Cursor / Windsurf / Cline
Most MCP clients accept this mcpServers JSON shape:
{
"mcpServers": {
"postgresql": {
"command": "uvx",
"args": ["mdev-postgresql-mcp-server"],
"env": {
"POSTGRES_HOST": "localhost",
"POSTGRES_PORT": "5432",
"POSTGRES_USER": "mcp_readonly",
"POSTGRES_PASSWORD": "change-me",
"POSTGRES_DB": "your_database"
}
}
}
}
For local development from this repository, use the installed console script path instead:
{
"mcpServers": {
"postgresql": {
"command": "/absolute/path/to/postgresql-mcp-server/.venv/bin/mdev-postgresql-mcp-server",
"args": [],
"env": {
"POSTGRES_HOST": "localhost",
"POSTGRES_PORT": "5432",
"POSTGRES_USER": "mcp_readonly",
"POSTGRES_PASSWORD": "change-me",
"POSTGRES_DB": "your_database"
}
}
}
}
Claude Code CLI
claude mcp add postgresql \
--env POSTGRES_HOST=localhost \
--env POSTGRES_PORT=5432 \
--env POSTGRES_USER=mcp_readonly \
--env POSTGRES_PASSWORD=change-me \
--env POSTGRES_DB=your_database \
-- uvx mdev-postgresql-mcp-server
VS Code MCP
VS Code uses the same command/args/env model in its MCP configuration:
{
"servers": {
"postgresql": {
"type": "stdio",
"command": "uvx",
"args": ["mdev-postgresql-mcp-server"],
"env": {
"POSTGRES_HOST": "localhost",
"POSTGRES_PORT": "5432",
"POSTGRES_USER": "mcp_readonly",
"POSTGRES_PASSWORD": "change-me",
"POSTGRES_DB": "your_database"
}
}
}
}
Tools
| Tool | Purpose | Safety |
|---|---|---|
postgresql_list_tables |
List public base tables | Read-only |
postgresql_describe_table |
Show columns and metadata for a table | Read-only |
postgresql_execute_read_query |
Run bounded SQL under read-only transaction mode | Read-only |
postgresql_execute_write_query |
Run a single approved modifying SQL statement and commit | Destructive |
postgresql_explain_query |
Return PostgreSQL EXPLAIN output for a single query |
Read-only |
postgresql_get_database_summary |
Return database version and table count | Read-only |
postgresql_get_relationships |
Inspect foreign-key relationships | Read-only |
postgresql_analyze_indexes |
Inspect indexes and sizes | Read-only |
postgresql_preview_table |
Return up to 10 rows from a table | Read-only |
postgresql_search_sql_definitions |
Search public SQL routines/functions | Read-only |
Resources
postgres://list_tablesreturns public table names.postgres://schema/{table_name}returns a generated schema statement for a table.
Smoke Check
Without a database, verify syntax with:
python -m py_compile src/postgresql_mcp_server/server.py
With a configured database, start the server and use your MCP client to call list_tables.
Distribution
This server is published through the standard Python MCP distribution path:
- PyPI package:
mdev-postgresql-mcp-server - MCP Registry name:
io.github.musaddiq-dev/postgresql-mcp-server - Runtime hint:
uvx - Transport:
stdio
The mcp-name marker at the top of this README is required for MCP Registry ownership verification. Users should prefer uvx mdev-postgresql-mcp-server in local MCP client configurations.
Security Notes
- Do not commit
.envor MCP client configs containing credentials. - Use least-privilege database users.
- Treat
execute_write_queryas destructive and require explicit user approval in your MCP client. - Review generated SQL before running write-capable tools.
License
MIT
PostgreSQL MCP questions
How do I add PostgreSQL MCP to Claude Code?
Run claude mcp add --env 'POSTGRES_DB=<POSTGRES_DB>' --env 'POSTGRES_HOST=<POSTGRES_HOST>' --env 'POSTGRES_PORT=<POSTGRES_PORT>' --env 'POSTGRES_USER=<POSTGRES_USER>' --env 'POSTGRES_PASSWORD=<YOUR_POSTGRES_PASSWORD>' postgresql-mcp-server -- uvx mdev-postgresql-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add PostgreSQL MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does PostgreSQL MCP provide?
It exposes 10 tools, including postgresql_list_tables, postgresql_describe_table, postgresql_execute_read_query, postgresql_execute_write_query, postgresql_explain_query.
Is it safe to run queries with this server?
The server provides a read-only tool that runs in a PostgreSQL read-only transaction mode and rolls back after execution to ensure safety.
Can the server modify my database?
Yes, the postgresql_execute_write_query tool can modify data or schema if the connected user has permission, so it should be used with caution.
What are the system requirements?
You need Python 3.11 or higher and a PostgreSQL database.