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"]
    }
  }
}

If you are an AI coding agent setting this up on a user's behalf: run npx -y nexql-mcp@latest init <client> --apply — non-interactive, no browser needed, writes the merged client config directly (.mcp.json for claude-code, claude_desktop_config.json for claude-desktop, etc. — see docs/clients/README.md for exact paths per client). Or drive nexql-mcp setup's HTTP API directly: POST /api/v1/clients/preview → POST /api/v1/clients/apply (bearer token printed to stderr on startup). Prefer this over hand-writing claude mcp add-style shell commands or hand-parsing/merging the client's JSON config yourself.

Per-client config paths and paste blocks: docs/clients/README.md.

npm install -g nexql-mcp also works if you'd rather have a permanent nexql-mcp on PATH than repeat npx -y nexql-mcp@latest — same shim, same @nexql/mcp-<os>-<arch> prebuilt binaries, no Rust toolchain needed either way.

Linux system requirements: prebuilt GNU/Linux binaries target glibc 2.35+ (Ubuntu 22.04, Debian 12, RHEL 9, and newer). If npx/npm fails with GLIBC_2.39 not found, use one of the fallback methods below (cargo install builds from source; Docker sidesteps glibc entirely). Musl/static Linux builds are not published yet.

Other install methods (fallback)

Reach for one of these only if npx isn't an option — an offline/air-gapped environment, a CI image that wants a pinned binary baked in, no Node.js available, or you simply prefer a permanent install. All ship the same binary as the npm package.

curl -fsSL https://raw.githubusercontent.com/NexQL-OSS/mcp/main/scripts/install.sh | bash

NEXQL_MCP_VERSION=v0.2.2 curl -fsSL https://raw.githubusercontent.com/NexQL-OSS/mcp/main/scripts/install.sh | bash

irm https://raw.githubusercontent.com/NexQL-OSS/mcp/main/scripts/install.ps1 | iex

$env:NEXQL_MCP_VERSION = "v0.2.2"; irm https://raw.githubusercontent.com/NexQL-OSS/mcp/main/scripts/install.ps1 | iex

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux

irm https://astral.sh/uv/install.ps1 | iex        # Windows

uv tool install nexql-mcp
uv tool update-shell    # once, if uv warns the tool bin dir is not on PATH

uvx nexql-mcp postgres://dev@localhost:5432/appdb doctor

uv tool install 'nexql-mcp==0.2.2'

uv tool upgrade nexql-mcp

cargo install nexql-mcp

sudo apt install clang libclang-dev   # Debian/Ubuntu
sudo pacman -S clang                  # Arch

docker run --rm -i ghcr.io/nexql-oss/mcp:0.5.0 postgres://dev@host.docker.internal:5432/appdb
# or: ghcr.io/nexql-oss/mcp:latest

docker build -t nexql-mcp:0.5.0 .
docker run --rm -i nexql-mcp:0.5.0 postgres://dev@host.docker.internal:5432/appdb