PostgreSQL MCP Server

postgres-mcp

PostgreSQL MCP Server binding the Model Context Protocol to a secure PostgreSQL sandbox.

Features Code Mode — a revolutionary approach that provides access to all 278 tools through a secure, true V8 isolate (worker_threads), eliminating the massive token overhead of multi-step tool calls. Also includes schema introspection, migration tracking, smart tool filtering, deterministic error handling, connection pooling, HTTP/SSE Transport, OAuth 2.1 authentication, and extension support for citext, ltree, pgcrypto, pg_cron, pg_stat_kcache, pgvector, PostGIS, and HypoPG.

278 Specialized Tools · 24 Resources · 21 AI-Powered Prompts

[Docker Hub](https://hub.docker.com/r/writenotenow/postgres-mcp) • [npm Package](https://www.npmjs.com/package/@neverinfamous/postgres-mcp) • [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/postgres-mcp) • [Wiki](https://github.com/neverinfamous/postgres-mcp/wiki) • [Tool Reference](https://github.com/neverinfamous/postgres-mcp/wiki/Tool-Reference) • [Changelog](https://github.com/neverinfamous/postgres-mcp/blob/main/CHANGELOG.md)

🎯 What Sets Us Apart

Suggested Rule (Add to AGENTS.md, GEMINI.md, etc)

MCP TOKEN MANAGEMENT:

• Token Visibility: When interacting with postgres-mcp, always monitor the _meta.tokenEstimate (or metrics.tokenEstimate in Code Mode) returned in tool responses.
• Audit Resource: Use the postgres://audit resource to review session-level token consumption and identify high-cost operations.
• Proactive Efficiency: If operations are consuming high token counts, prefer code mode and proactively use limit parameters.

🚀 Quick Start

Prerequisites

• PostgreSQL 12-18 (tested with PostgreSQL 18.1)
• Docker (recommended) or Node.js 24+ (LTS)

Docker (Recommended)

docker pull writenotenow/postgres-mcp:latest

Add to your ~/.cursor/mcp.json or Claude Desktop config:

{

"mcpServers": { "postgres-mcp": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "POSTGRES_HOST", "-e", "POSTGRES_PORT", "-e", "POSTGRES_USER", "-e", "POSTGRES_PASSWORD", "-e", "POSTGRES_DATABASE", "writenotenow/postgres-mcp:latest", "--tool-filter", "codemode", "--audit-log", "/tmp/postgres-logs/audit.jsonl" ], "env": { "POSTGRES_HOST": "host.docker.internal", "POSTGRES_PORT": "5432", "POSTGRES_USER": "your_username", "POSTGRES_PASSWORD": "your_password", "POSTGRES_DATABASE": "your_database" } } } }

Note for Docker: Use host.docker.internal to connect to PostgreSQL running on your host machine.

📖 Full Docker guide: DOCKER_README.md · Docker Hub

npm

npm install -g @neverinfamous/postgres-mcp

postgres-mcp --transport stdio --postgres postgres://user:password@localhost:5432/database

From Source

git clone https://github.com/neverinfamous/postgres-mcp.git

cd postgres-mcp npm install npm run build node dist/cli.js --transport stdio --postgres postgres://user:password@localhost:5432/database

Development

See [From Source](#from-source) above for setup. After cloning:

npm run lint && npm run typecheck  # Run checks

npm run bench # Run performance benchmarks node dist/cli.js info # Test CLI node dist/cli.js list-tools # List available tools

Benchmarks

Run npm run bench to execute the performance benchmark suite (10 files, 93+ scenarios) powered by Vitest Bench. Use npm run bench:verbose for detailed table output.

Performance Highlights (Node.js 24, Windows 11):

Full benchmark results and methodology are available on the Performance wiki page.

🔗 Database Connection Scenarios

🛠️ Tool Filtering

[!IMPORTANT]

All tool groups include Code Mode (pg_execute_code) by default. To exclude it, add -codemode to your filter: --tool-filter cron,pgcrypto,-codemode

💡 Code Mode (--tool-filter codemode) is the recommended configuration — it exposes pg_execute_code, a secure, true V8 isolate sandbox providing access to all 278 tools' worth of capability with up to 90% token savings. See Tool Filtering for alternatives.

• Requires `admin` OAuth scope — execution is logged for audit

📖 [See Full Installation Guide →](https://github.com/neverinfamous/postgres-mcp#readme)

What Can You Filter?

The --tool-filter argument accepts groups or tool names — mix and match freely:

| Groups only | `core,jsonb,transac