# Postgres Mcp

> Secure PostgreSQL Administration & Observability with Code Mode— True V8 Isolate Sandbox Replacing 278 Specialized Tools for up to 90% Token Savings. Includes Tool Filtering, Payload Optimization, HTTP/SSE, OAuth 2.1, Audit & Token Logging, Deterministic Error Handling, Support for 12 Extensions (pgvector, PostGIS, pg_partman, pg_cron & more).

- **Type:** MCP server
- **Install:** `agentstack add mcp-neverinfamous-postgres-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [neverinfamous](https://agentstack.voostack.com/s/neverinfamous)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [neverinfamous](https://github.com/neverinfamous)
- **Source:** https://github.com/neverinfamous/postgres-mcp
- **Website:** https://search.adamic.tech/

## Install

```sh
agentstack add mcp-neverinfamous-postgres-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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**

[](https://github.com/neverinfamous/postgres-mcp)

[](https://hub.docker.com/r/writenotenow/postgres-mcp)
[](https://opensource.org/licenses/MIT)
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/postgres-mcp)
[](https://www.npmjs.com/package/@neverinfamous/postgres-mcp)
[](https://github.com/neverinfamous/postgres-mcp/blob/main/SECURITY.md)

[](https://github.com/neverinfamous/postgres-mcp)
[](https://github.com/neverinfamous/postgres-mcp/actions/workflows/e2e.yml)
[](https://github.com/neverinfamous/postgres-mcp)
[](https://github.com/neverinfamous/postgres-mcp)

**[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

| Feature                             | Description                                                                                                                                                                                                         |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Code Mode (V8 Isolate)**          | **Massive Token Savings:** Execute complex, multi-step operations inside a secure, true V8 isolate (`worker_threads`). Stop burning tokens on back-and-forth tool calls and reduce your AI overhead by up to 90%.   |
| **Deterministic Error Handling**    | No more cryptic database errors causing AI hallucinations. We intercept and translate raw SQL exceptions into clear, actionable advice so your agent knows exactly how to recover without guessing.                 |
| **278 Token-Optimized Tools**       | The largest PostgreSQL toolset on the MCP registry. Every query uses zero-cost token estimation and smart dataset truncation, ensuring agents always see the big picture without blowing their context windows.     |
| **OAuth 2.1 + Granular Control**    | Real enterprise security. Authenticate via OAuth 2.1 and control exactly who can read, write, or administer your database with precision scopes mapped down to the specific tool layer.                             |
| **Audit Trails & Semantic Diffing** | Total accountability. Track exactly what your AI is doing with detailed JSON logs, automatically snapshot schemas before mutations, and confidently review semantic row-by-row diffs before restoring data.         |
| **24 Resources & 21 Prompts**       | Instant database meta-awareness. Agents automatically read real-time health, performance, and replication metrics, and can invoke built-in prompt workflows for query tuning and schema design.                     |
| **Introspection & Migrations**      | Prevent costly mistakes. Let your AI simulate the cascade impact of schema changes, safely order foreign-key updates, and track migration history automatically.                                                    |
| **8 Extension Ecosystems**          | Ready for advanced workloads. First-class API support for **pgvector** (AI search), **PostGIS** (geospatial), **pg_cron**, **pgcrypto**, and more—all strictly typed and validated out of the box.                  |
| **Smart Tool Filtering**            | Give your agent exactly what it needs without overflowing IDE limits. Dynamically compile your server with any combination of our 25 distinct tool groups.                                                          |
| **Enterprise Infrastructure**       | Built for production. Blazing fast (millions of ops/sec), protected against SQL injection, features high-performance connection pooling, and supports both Streamable HTTP and Legacy SSE protocols simultaneously. |

## 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)

```bash
docker pull writenotenow/postgres-mcp:latest
```

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

```json
{
  "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_README.md) · [Docker Hub](https://hub.docker.com/r/writenotenow/postgres-mcp)

### npm

```bash
npm install -g @neverinfamous/postgres-mcp
postgres-mcp --transport stdio --postgres postgres://user:password@localhost:5432/database
```

### From Source

```bash
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:

```bash
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](https://vitest.dev/guide/features.html#benchmarking). Use `npm run bench:verbose` for detailed table output.

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

| Area                        | Benchmark                                | Throughput    |
| --------------------------- | ---------------------------------------- | ------------- |
| **Tool Dispatch**           | Map.get() single tool lookup             | ~6.9M ops/sec |
| **WHERE Validation**        | Simple clause (combined regex fast-path) | ~3.7M ops/sec |
| **Identifier Sanitization** | validateIdentifier()                     | ~4.4M ops/sec |
| **Auth — Token Extraction** | extractBearerToken()                     | ~2.7M ops/sec |
| **Auth — Scope Checking**   | hasScope()                               | ~5.3M ops/sec |
| **Rate Limiting**           | Single IP check                          | ~2.3M ops/sec |
| **Logger**                  | Filtered debug (no-op path)              | ~5.4M ops/sec |
| **Schema Parsing**          | MigrationInitSchema.parse()              | ~2.1M ops/sec |
| **Metadata Cache**          | Cache hit + miss pattern                 | ~1.7M ops/sec |
| **Sandbox Creation**        | CodeModeSandbox.create() cold start      | ~863 ops/sec  |

> Full benchmark results and methodology are available on the [Performance wiki page](https://github.com/neverinfamous/postgres-mcp/wiki/Performance).

## 🔗 Database Connection Scenarios

| Scenario                       | Host to Use                           | Example Connection String                         |
| ------------------------------ | ------------------------------------- | ------------------------------------------------- |
| **PostgreSQL on host machine** | `localhost` or `host.docker.internal` | `postgres://user:pass@localhost:5432/db`          |
| **PostgreSQL in Docker**       | Container name or network             | `postgres://user:pass@postgres-container:5432/db` |
| **Remote/Cloud PostgreSQL**    | Hostname or IP                        | `postgres://user:pass@db.example.com:5432/db`     |

| Provider           | Example Hostname                                 |
| ------------------ | ------------------------------------------------ |
| AWS RDS PostgreSQL | `your-instance.xxxx.us-east-1.rds.amazonaws.com` |
| Google Cloud SQL   | `project:region:instance` (via Cloud SQL Proxy)  |
| Azure PostgreSQL   | `your-server.postgres.database.azure.com`        |
| Supabase           | `db.xxxx.supabase.co`                            |
| Neon               | `ep-xxx.us-east-1.aws.neon.tech`                 |

### 🛠️ 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](#%EF%B8%8F-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:

| Filter Pattern | Example                    | Description               |
| -------------- | -------------------------- | ------------------------- |
| Groups only    | `core,jsonb,transactions`  | Combine individual groups |
| Tool names     | `pg_read_query,pg_explain` | Custom tool selection     |
| Group + Tool   | `core,+pg_stat_statements` | Extend a group            |
| Group - Tool   | `core,-pg_drop_table`      | Remove specific tools     |

### Tool Groups (25 Available)

| Group           | Tools | Description                                                           |
| --------------- | ----- | --------------------------------------------------------------------- |
| `codemode`      | 1     | Code Mode (sandboxed code execution) 🌟 **Recommended**               |
| `core`          | 21    | Read/write queries, tables, indexes, convenience/drop tools           |
| `transactions`  | 9     | BEGIN, COMMIT, ROLLBACK, savepoints, status                           |
| `jsonb`         | 21    | JSONB manipulation, queries, and pretty-print                         |
| `text`          | 14    | Full-text search, fuzzy matching                                      |
| `performance`   | 25    | EXPLAIN, query analysis, optimization, diagnostics, anomaly detection |
| `admin`         | 12    | VACUUM, ANALYZE, REINDEX, insights                                    |
| `monitoring`    | 12    | Database sizes, connections, status                                   |
| `backup`        | 13    | pg_dump, COPY, restore, audit backups                                 |
| `schema`        | 13    | Schemas, views, sequences, functions, triggers                        |
| `introspection` | 7     | Dependency graphs, cascade simulation, schema analysis                |
| `migration`     | 7     | Schema migration tracking and management                              |
| `partitioning`  | 7     | Native partition management                                           |
| `stats`         | 20    | Statistical analysis, window functions, outlier detection             |
| `vector`        | 17    | pgvector (AI/ML similarity search)                                    |
| `postgis`       | 16    | PostGIS (geospatial)                                                  |
| `cron`          | 9     | pg_cron (job scheduling)                                              |
| `partman`       | 11    | pg_partman (auto-partitioning)                                        |
| `kcache`        | 8     | pg_stat_kcache (OS-level stats)                                       |
| `citext`        | 7     | citext (case-insensitive text)                                        |
| `ltree`         | 9     | ltree (hierarchical data)                                             |
| `pgcrypto`      | 10    | pgcrypto (encryption, UUIDs)                                          |
| `security`      | 10    | Security auditing, SSL, firewall, data masking, privilege analysis    |
| `roles`         | 13    | Role management, privileges, membership, RLS                          |
| `docstore`      | 10    | JSONB document collections (NoSQL-style CRUD, indexing)               |

### Syntax Reference

| Prefix   | Target | Example          | Effect                                      |
| -------- | ------ | ---------------- | ------------------------------------------- |
| _(none)_ | Group  | `core`           | **Whitelist Mode:** Enable ONLY this group  |
| _(none)_ | Tool   | `pg_read_query`  | **Whitelist Mode:** Enable ONLY this tool   |
| `+`      | Group  | `+vector`        | Add tools from this group to current set    |
| `-`      | Group  | `-admin`         | Remove tools in this group from current set |
| `+`      | Tool   | `+pg_explain`    | Add one specific tool                       |
| `-`      | Tool   | `-pg_drop_table` | Remove one specific tool                    |

## 🌐 HTTP/SSE Transport (Remote Access)

For remote access, web-based clients, or HTTP-compatible MCP hosts, use the HTTP transport:

```bash
node dist/cli.js \
  --transport http \
  --port 3000 \
  --postgres "postgres://user:pass@localhost:5432/db"
```

**Docker:**

```bash
docker run --rm -p 3000:3000 \
  -e POSTGRES_URL=postgres://user:pass@host:5432/db \
  writenotenow/postgres-mcp:latest \
  --transport http --port 3000
```

The server supports **two MCP transport protocols simultaneously**, enabling both modern and legacy clients to connect:

### Streamable HTTP (Recommended)

Modern protocol (MCP 2025-03-26) — single endpoint, session-based:

| Method   | Endpoint | Purpose                                          |
| -------- | -------- | ------------------------------------------------ |
| `POST`   | `/mcp`   | JSON-RPC requests (initialize, tools/list, etc.) |
| `GET`    | `/mcp`   | SSE stream for server notifications              |
| `DELETE` | `/mcp`   | Session termination                              |

Sessions are managed via the `Mcp-Session-Id` header.

### Stateless Mode

For serverless/stateless deployments where sessions are not needed:

```bash
node dist/cli.js --transport http -

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [neverinfamous](https://github.com/neverinfamous)
- **Source:** [neverinfamous/postgres-mcp](https://github.com/neverinfamous/postgres-mcp)
- **License:** MIT
- **Homepage:** https://search.adamic.tech/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-neverinfamous-postgres-mcp
- Seller: https://agentstack.voostack.com/s/neverinfamous
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.