mcp-postgres

mcp-postgres is a high-performance MCP server that brings PostgreSQL into Claude Desktop and any MCP-compatible AI tool. 135 PostgreSQL tools, lock-free connection pooling, sub-10ms latency.

Quick Start

Install

# From crates.io
cargo install mcp-postgres

# Or from Homebrew (macOS)
brew tap corporatepiyush/mcp-postgres
brew install mcp-postgres

Run

# Stdio mode (for Claude Desktop)
mcp-postgres --database-url "postgres://user:pass@localhost:5432/mydb" --stdio

# TCP server (port 3000)
mcp-postgres --database-url "postgres://user:pass@localhost:5432/mydb"

# HTTP/2 server (port 3001)
mcp-postgres --database-url "postgres://user:pass@localhost:5432/mydb" --http-port 3001

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "mcp-postgres",
      "args": ["--database-url", "postgres://user:pass@localhost:5432/mydb", "--stdio"]
    }
  }
}

Complete setup guide →

Why mcp-postgres?

Feature	mcp-postgres	DIY / psql
135 purpose-built tools	Schema inspection, DDL, monitoring, replication, batch ops, security audit, text search, extensions, maintenance, and more	You build every query from scratch
Lock-free connection pool	Zero-mutex `crossbeam::ArrayQueue` — pure CAS loops, no kernel overhead	Deadpool or manual `Mutex<VecDeque>`
Dual-protocol	TCP (3000) + HTTP/2 (3001) + stdio — one binary, three transports	Multiple servers to wire up
Sub-10ms latency	Allocated for AI interactivity — hot path is allocation-free	Unpredictable
SQL injection prevention	Every identifier validated, `quote_ident` sanitization, structured predicates	Manual parameterization
PG version-aware	Queries verified against PG 16–18 docs, graceful fallbacks for version differences	Version-specific failures

Command-Line Options

Usage: mcp-postgres [OPTIONS]

Options:
  -d, --database-url <URL>       PostgreSQL connection string
  -H, --host <HOST>              TCP server host             [127.0.0.1]
  -p, --port <PORT>              TCP server port             [3000]
      --http-port <PORT>         HTTP/2 server port          [3001]
      --min-connections <N>      Min pool connections        [5]
      --max-connections <N>      Max pool connections        [20]
      --log-level <LEVEL>        Log level                   [info]
      --enable-metrics           Prometheus /metrics endpoint
      --metrics-port <PORT>      Metrics port                [9090]
      --stdio                    Stdio mode (Claude Desktop)
      --access-mode <MODE>       unrestricted, restricted    [unrestricted]
  -h, --help                     Print help
  -V, --version                  Print version

Protocol & API

JSON-RPC 2.0 over TCP, HTTP/2, or stdio.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": { "name": "list_tables", "arguments": {} },
  "id": 1
}

Tools (135 Total)

Performance

Lock-Free Connection Pool (v4.0.0)

No mutexes. No semaphores. Just CAS loops.

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│  Task 1     │     │  crossbeam::     │     │  Task 2     │
│  (acquire)  │────▶│  ArrayQueue      │◀────│  (release)  │
└─────────────┘     │  CachePadded     │     └─────────────┘
                    │  Head/Tail       │
                    │  (CAS only)      │
                    └──────────────────┘

Metric	Deadpool (v3.x)	LockFreePool (v4.0.0)
Lock acquisitions per acquire+release	3+ (Mutex + Semaphore)	0
Allocation on hot path	Yes (VecDeque growth)	Zero (pre-allocated)
False sharing	Likely (adjacent fields)	Cache-padded atomics
Inlining	Cross-crate, opaque	Monomorphic, LTO-friendly
Dependencies	2 (deadpool + deadpool-postgres)	0 external (crossbeam already in tree)

Sub-10ms latency is guaranteed by design: zero allocation on the hot path, monomorphic dispatch, cache-line-isolated atomics, and a single-pointer CAS for connection handoff.

Architecture

┌─────────────────┐         ┌─────────────────┐
│   TCP Client    │         │   HTTP Client   │
│  (port 3000)    │         │  (port 3001)    │
└────────┬────────┘         └────────┬────────┘
         └─────────────┬─────────────┘
                       │
              ┌────────┴────────┐
              │   JSON-RPC 2.0  │
              │  (MCP Protocol) │
              └────────┬────────┘
                       │
          ┌────────────┴────────────┐
          │   Tool Dispatcher       │
          │   (135 tools)           │
          └────────────┬────────────┘
                       │
          ┌────────────┴────────────┐
          │   Connection Pool       │
          │   (lock-free, CAS-only) │
          │   Min: 5, Max: 20       │
          └────────────┬────────────┘
                       │
              ┌────────┴────────┐
              │  PostgreSQL DB  │
              └─────────────────┘

Key Design Principles

Stateless HTTP — Each request is independent. Transaction state isolated per-connection.
Lock-free pooling — crossbeam::ArrayQueue with CachePadded atomics. Zero mutex acquisitions.
Input validation at the boundary — SQL capped at 10K chars, identifiers at 255, batch rows at 1K. SQL injection prevention via quote_ident.
PG version-aware queries — Verified against PG 16–18. Graceful fallbacks when views/columns differ across versions.

License

Apache-2.0

Support

GitHub Issues

mcp-postgres 4.0.1