NexQL Postgres MCP server

nexql-mcp

Standalone Postgres MCP server — schema-aware, read-only by default, installable everywhere.

NexQL Pro ships an in-process MCP server locked to VS Code (pro/src/mcp/). This repo extracts that capability into an independent Rust binary any MCP client can spawn: Claude Desktop, Cursor, VS Code Copilot, Zed, etc.

Status: Phases 0–6 + Phase 7 extension cutover (stdio spawn) + Phase 8 HTTP (bearer, sessions, rate limit) + Phase 9 write/admin tools landed. 54 tools across Schema, Query, Context, Perf, Write, and Admin. Full OAuth gateway stays pro-only; session-store LRU eviction cap not yet implemented. See docs/CUTOVER.md.

Why this exists

Competing Postgres MCP servers expose connect → run query → return rows. Models hallucinate table names against schemas that do not exist. NexQL's moat is the offline schema index (TF-IDF, join graph with inferred FKs, value profiles, optional embeddings, RRF fusion) built in pro/src/features/dbindex/. This repo ports that index plus 54 query/schema/DBA/meta tools from Pro into a fast, trivially installable binary.

Architecture

crates/
├── nexql-mcp/      CLI, subcommands, wiring (binary)
├── nexql-proto/    MCP JSON-RPC types, transports
├── nexql-tools/    tool registry, schemas, executors
├── nexql-index/    dbindex port (builder, store, lexical, joins, embed)
├── nexql-conn/     connection resolution, pool, credentials
└── nexql-policy/   access modes, allow/deny, PII, caps, audit
npm/                npx shim (per-platform optionalDependencies)
mcpb/               one-click Claude Desktop bundle
docs/               per-client setup, tool reference

Layering is one-directional: policy + conn are leaves → index → tools → binary. nexql-tools never depends on nexql-proto.

Scope boundary: nexql-mcp manages objects within a connected database (tables, indexes, columns, …), not the database catalog itself. CREATE DATABASE / DROP DATABASE are rejected in every access mode — permanent, intentional scope, not a gap. See docs/tools/README.md and docs/REFERENCE.md.

Install

npx — recommended, zero install

npx -y nexql-mcp@latest postgres://dev@localhost:5432/appdb doctor

-y skips the "ok to proceed?" confirmation prompt; @latest always resolves the newest published release instead of whatever npx happens to have cached — always use both together. This is the desired way to run nexql-mcp: no separate install step, nothing added to PATH, works identically whether a human is typing it or an AI agent is running it on your behalf. Requires Node.js (npx ships with it) — nothing else.

# Verify
npx -y nexql-mcp@latest --version

# Setup
npx -y nexql-mcp@latest setup  # initialize connections and db profiles

# Wire your MCP client (or run the guided wizard)
npx -y nexql-mcp@latest init cursor          # Cursor
npx -y nexql-mcp@latest init claude-desktop  # Claude Desktop
npx -y nexql-mcp@latest init vscode-copilot  # VS Code Copilot
npx -y nexql-mcp@latest tui                  # interactive profile + client wiring

Client config (command/args) uses the same pattern — no install step for the client to rely on either:

{
  "mcpServers": {
    "nexql-mcp": {
      "command": "npx",
      "args": ["-y", "nexql-mcp@latest", "--profile", "mydb"]
    }
  }
}

Shortened. The full README is on GitHub.