PostgreSQL MCP Server

io.github.musaddiq-devPublished by GitHub account musaddiq-devv0.1.2Updated Oct 24, 2026

Python MCP server for PostgreSQL database inspection and querying

VerifiedSTDIODesktop onlyDatabases Data & Analytics

Server details

Identifier: io.github.musaddiq-dev/postgresql-mcp-server
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account musaddiq-dev for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.musaddiq-dev%2Fpostgresql-mcp-server.svg)](https://sourceweft.com/mcp/io.github.musaddiq-dev%2Fpostgresql-mcp-server?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

A local Python MCP server that lets an assistant inspect and query a PostgreSQL database: list tables, read schemas, run bounded read-only SQL and explain plans

What you can do: List tables and describe table columns and metadata, plus a database summary with version and table count and a search of SQL routines and functions. Run bounded read-only SQL in a read-only transaction, explain query plans, and preview up to 10 rows of a table. Inspect foreign-key relationships and indexes with sizes. Execute a single modifying statement (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, TRUNCATE) that commits. Read passive resources for the table list and per-table schema details.
When to use it: Useful when an assistant needs to explore an unfamiliar PostgreSQL schema, answer questions from live data, or check query plans and indexes without leaving the chat. Suited to local development and analysis where a database connection is already available.
Requirements: Runs locally over stdio as a Python package (Python 3.11+) launched with uvx, and needs a reachable PostgreSQL database. Required environment variables: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_DB; POSTGRES_PASSWORD is optional. POSTGRES_READ_QUERY_LIMIT caps rows returned by read queries. An MCP-compatible client is needed.

Before you install

The server includes a write tool that can modify data and schema and commits changes; the README calls it destructive and advises against auto-approving it and reviewing generated SQL first. Use a least-privilege, ideally read-only database user. POSTGRES_PASSWORD is a secret; do not commit .env files or client configs containing credentials.

Installation

In SourceWeft

Open PostgreSQL MCP Server in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

For local development from source:

bash

git clone https://github.com/musaddiq-dev/postgresql-mcp-server.gitcd postgresql-mcp-serverpython -m venv .venvsource .venv/bin/activatepip install -e .

git clone https://github.com/musaddiq-dev/postgresql-mcp-server.gitcd postgresql-mcp-serverpython -m venv .venvsource .venv/bin/activatepip install -e .

Configuration

Copy the example environment file and update it with your database connection details.

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:

sql

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;

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

From a local checkout before PyPI publication, run:

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:

json

{  "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"      }    }  }}

{  "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:

json

{  "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"      }    }  }}

{  "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

bash

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

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:

json

{  "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"      }    }  }}

{  "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_tables returns public table names.
postgres://schema/{table_name} returns a generated schema statement for a table.

Smoke Check

Without a database, verify syntax with:

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 .env or MCP client configs containing credentials.
Use least-privilege database users.
Treat execute_write_query as destructive and require explicit user approval in your MCP client.
Review generated SQL before running write-capable tools.

License

MIT

Source: README.md at commit 3e4ecf6

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts