JaviMaligno/postgres_mcp

MCP server for PostgreSQL database operations. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.
Language Versions
This repository contains both **TypeScript** and **Python** implementations:
| Version | Directory | Status | MCP protocol | Installation |
|---------|-----------|--------|--------------|--------------|
| **TypeScript** | /typescript | ✅ Recommended (Smithery) | 2026-07-28 (SDK v2) | npm install -g @javiagui/postgresql-mcp |
| Python | /python | ✅ Stable | 2026-07-28 (SDK v2) | pipx install postgresql-mcp |
> **Note**: The TypeScript version is used for Smithery deployments. Both versions provide identical functionality.
> **Protocol compatibility**: both servers speak the
> 2026-07-28 revision and are
> **dual-era** — clients that still open with the 2025-era initialize handshake are served
> exactly as before, so no client needs upgrading. The TypeScript package requires Node.js 20+;
> the Python package requires Python 3.10+.
Features
- **Query Execution**: Execute SQL queries with read-only protection by default
- **Schema Exploration**: List schemas, tables, views, and functions
- **Table Analysis**: Describe structure, indexes, constraints, and statistics
- **Performance Tools**: EXPLAIN queries and analyze table health
- **Security First**: SQL injection prevention, credential protection, read-only by default
- **MCP Prompts**: Guided workflows for exploration, query building, and documentation
- **MCP Resources**: Browsable database structure as markdown
Quick Start
TypeScript (Recommended for Smithery)
Python
**Full Installation Guide** - Includes database permissions setup, remote connections, and troubleshooting.
Configuration
Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| POSTGRES_HOST | | localhost | Database host |
| POSTGRES_PORT | | 5432 | Database port |
| POSTGRES_USER | ✅ | | Database user |
| POSTGRES_PASSWORD | ✅ | | Database password |
| POSTGRES_DB | ✅ | | Database name |
| POSTGRES_SSLMODE | | prefer | SSL mode |
| ALLOW_WRITE_OPERATIONS | | false | Enable INSERT/UPDATE/DELETE |
| QUERY_TIMEOUT | | 30 | Query timeout (seconds) |
| MAX_ROWS | | 1000 | Maximum rows returned |
Multiple databases
Most real work touches more than one database. Instead of editing this config and
restarting your client every time, declare several connections and pick one per
call by **alias**:
- **list_databases** returns the configured aliases with host, database name,
write permission and which is the default. **Credentials are never returned.**
- Every other tool takes an optional **database** argument naming an alias.
Omit it and you get the default connection — so an existing single-database
setup keeps working with no changes at all.
- **allowWrite is per connection**, falling back to ALLOW_WRITE_OPERATIONS.
A production replica stays read-only while a local database allows writes.
- default: true marks the connection used when database is omitted;
otherwise it is the first one declared. At most one connection may be marked
default.
- Each connection accepts either discrete fields (host, port, user,
password, database, sslmode) or a url DSN — and discrete fields
override the DSN, so you can reuse a URL and change one part of it.
- One pool per alias, opened lazily: a configured but unused database never
opens a socket.
POSTGRES_CONNECTIONS and the plain POSTGRES_* variables are **mutually