NexQL Postgres MCP

nexql-mcp

独立的 Postgres MCP 服务——了解架构，默认只读，可在任何地方安装。

NexQL Pro 附带一个仅限 VS Code 使用的进程内 MCP 服务（pro/src/mcp/）。本仓库将该功能提取为独立的 Rust 二进制文件，任何 MCP 客户端都可以启动它：Claude Desktop、Cursor、VS Code Copilot、Zed 等。

状态： 阶段 0–6、阶段 7 扩展切换（stdio 启动）、阶段 8 HTTP（bearer、会话、速率限制）和阶段 9 写入/管理工具均已完成。Schema、Query、Context、Perf、Write 和 Admin 共 54 个工具。完整的 OAuth 网关仍仅限 Pro 使用；尚未实现会话存储的 LRU 驱逐上限。参见 docs/CUTOVER.md。

为什么要做这个项目

其他 Postgres MCP 服务只提供 连接 → 运行查询 → 返回行。模型会针对不存在的架构臆造表名。NexQL 的优势在于离线架构索引（TF-IDF、含推断外键的连接图、值概况、可选嵌入、RRF 融合），该索引构建于 pro/src/features/dbindex/。本仓库将该索引以及 Pro 中的 54 个查询/架构/DBA/元数据工具移植为快速、易于安装的二进制文件。

架构

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

分层是单向的：policy 和 conn 是叶节点 → index → tools → 二进制文件。nexql-tools 不依赖 nexql-proto。

范围边界： nexql-mcp 管理已连接数据库内部的对象（表、索引、列等），而不管理数据库目录本身。在所有访问模式下，都会拒绝 CREATE DATABASE / DROP DATABASE——这是永久且有意设定的范围，并非功能缺失。参见 docs/tools/README.md 和 docs/REFERENCE.md。

安装

npx——推荐，零安装

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

-y 会跳过“是否继续？”确认提示；@latest 始终会解析到最新发布版本，而不是 npx 恰好缓存的版本——两者务必搭配使用。这是运行 nexql-mcp 的推荐方式：无需单独安装，不会向 PATH 添加任何内容，无论由人类输入命令，还是由 AI Agent 代为运行，效果都一样。需要 Node.js（随附 npx），不需要其他依赖。

# 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

客户端配置（command/args）使用相同模式——客户端同样无需依赖单独的安装步骤：

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

**如果你是代用户进行设置的 AI 编码 Agent：**运行 npx -y nexql-mcp@latest init <client> --apply——该命令以非交互方式运行，无需浏览器，可直接写入合并后的客户端配置（claude-code 对应 .mcp.json，claude-desktop 对应 claude_desktop_config.json 等；各客户端的准确路径参见 docs/clients/README.md）。或者直接调用 nexql-mcp setup 的 HTTP API：POST /api/v1/clients/preview → POST /api/v1/clients/apply（启动时打印到 stderr 的 bearer token）。建议使用此方式，而不是手动编写 claude mcp add 风格的 shell 命令，或自行解析并合并客户端的 JSON 配置。

各客户端的配置路径和粘贴内容：docs/clients/README.md。

如果你更愿意将永久的 nexql-mcp 安装到 PATH，而不是每次都重复运行 npx -y nexql-mcp@latest，也可以使用 npm install -g nexql-mcp——它们使用相同的封装脚本和相同的预编译 @nexql/mcp-<os>-<arch> 二进制文件，两种方式都不需要 Rust 工具链。

**Linux 系统要求：**预编译的 GNU/Linux 二进制文件面向 glibc 2.35 及以上版本（Ubuntu 22.04、Debian 12、RHEL 9 及更新版本）。如果 npx/npm 因 GLIBC_2.39 not found 而失败，请使用以下备用方法之一（cargo install 会从源代码构建；Docker 可完全绕开 glibc）。目前尚未发布 Musl/静态 Linux 构建版本。

其他安装方式（备用）

只有在无法使用 npx 时才选择以下方式——例如处于离线/隔离环境、CI 镜像需要预置固定版本的二进制文件、无法使用 Node.js，或你只是更喜欢永久安装。所有方式提供的二进制文件都与 npm 包相同。

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://[email protected]: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://[email protected]:5432/appdb

export LIBCLANG_PATH="${LIBCLANG_PATH:-/usr/lib}"   # or your llvm lib dir
cargo build --release -p nexql-mcp
./target/release/nexql-mcp postgres://dev@localhost:5432/appdb

以下命令假定 nexql-mcp 可通过 PATH 找到。如果你通过 npx 运行，请将每条命令中的 nexql-mcp 替换为 npx -y nexql-mcp@latest — 参见安装。

一次性连接，无需配置 — 直接传入连接字符串：

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

保存的配置 — 将连接写入 ~/.config/nexql-mcp/config.toml（使用 NEXQL_MCP_CONFIG 覆盖路径）：

default_profile = "local"

[profiles.local]
url = "postgres://dev@localhost:5432/appdb"
access_mode = "read"

[profiles.prod]
host = "prod.example.com"
dbname = "app"
user = "readonly_agent"
password_command = "op read op://vault/pg/password"   # never store plaintext secrets
sslmode = "verify-full"
access_mode = "read"
schemas = ["public", "billing"]
deny_tables = ["auth.*"]
pii_columns = ["public.users.ssn", "public.users.email"]
max_rows = 200

完整字段参考：docs/config.example.toml。然后直接运行（nexql-mcp）以使用 default_profile，或运行 nexql-mcp --profile prod。

连接前先测试，再将其接入客户端：

nexql-mcp postgres://dev@localhost:5432/appdb doctor
# or, for a saved profile (note: --profile goes before the subcommand):
nexql-mcp --profile prod doctor

引导式设置 — 交互式配置编辑器，并可一键接入你使用的任意客户端：

• nexql-mcp tui — 终端 UI（参见下文交互式 TUI）
• nexql-mcp setup — 在本机回环地址上运行的浏览器 UI（配置、客户端接入、npx/路径启动切换）；也可运行 npx -y nexql-mcp@latest setup

接入客户端

nexql-mcp postgres://dev@localhost:5432/appdb init cursor

支持 init 的客户端：claude | claude-desktop | claude-code | cursor | vscode | vscode-copilot | zed | windsurf | continue | jetbrains | openai-agents。

各客户端的粘贴配置块：docs/clients/README.md。

工具范围 / 上下文预算

--tools query|dba|meta|full（环境变量：NEXQL_MCP_TOOLS）用于限制向客户端公布哪些工具 — 这是用于控制上下文窗口预算的开关，而非安全边界。它仅提供参考：真正限制调用操作范围的是 nexql-policy 的 access_mode（read/write/admin，通过 --access-mode 或配置中的 access_mode 设置）。只有在想减少加载到 Agent 上下文窗口中的工具架构 JSON 时，才选择范围更窄的配置：

• query — 核心查询/发现工具（架构搜索、run_select、explain_query，等等）
• dba — 监控/管理工具（健康检查、索引建议、锁，等等）
• meta — 最小的初始范围，并提供 discover_tools，以便按需延迟激活其余工具（参见 docs/tools/README.md）
• full（默认）— 所有活动工具

各配置包含的确切工具：nexql-tools/src/registry.rs 中的 QUERY_PROFILE/DBA_PROFILE/META_PROFILE/ACTIVE 常量。

与 NexQL VS Code 扩展配合使用

如果你已经在使用 ric-v.postgres-explorer（+ NexQL Pro），则无需进行上述任何操作 — 扩展可以自行启动此二进制文件，并复用你已有的已保存连接，无需单独的 config.toml。

1. 设置 → 搜索 NexQL: Mcp: Enabled（postgresExplorer.mcp.enabled）→ 勾选。默认关闭。
2. 就这么简单 — 设置会立即生效（无需重新加载），并读取 postgresExplorer.connections 中已保存的所有连接。它会在 Copilot Chat / Agent 模式工具选择器中显示为名为 NexQL 的 MCP 服务。

扩展按以下顺序查找二进制文件：postgresExplorer.mcp.binaryPath 设置 → NEXQL_MCP_BIN 环境变量 → 扩展随附的副本 → PATH 中的 nexql-mcp（即通过上文 npm/cargo/curl 安装的任何版本）。如果希望扩展使用特定安装版本，请明确设置 postgresExplorer.mcp.binaryPath。

交互式 TUI

nexql-mcp tui

引导式配置文件编辑器：添加、编辑或删除连接配置文件；保存前实时测试连接；然后从 7 个客户端（Claude Desktop、Claude Code、Cursor、VS Code、Copilot Chat、Zed、Windsurf）中选择任意客户端，一次性将配置接入。系统会读取每个所选客户端的实际配置文件，合并配置（保留现有的无关服务），显示差异，并且只有在你确认后才写入；同时会在同一目录中保留带时间戳的备份。continue / jetbrains / openai-agents 没有安全的磁盘合并目标，因此会像 init 一样，将这些配置作为可复制粘贴的代码片段显示在摘要界面中。

按键：n 新建 · e/Enter 编辑 · d 删除 · t 测试 · w 接入客户端 · q 退出。如果没有其他方式解析出连接，直接运行 nexql-mcp（不带 URL 或标志）会自动启动 TUI。

发布

推送 v* 标签会触发 .github/workflows/release.yml：构建 darwin arm64/x64、linux gnu arm64/x64 和 windows x64 版本；将归档文件、各平台的 .mcpb 捆绑包、 CycloneDX SBOM 和渲染后的 Homebrew 公式附加到 GitHub 发布；发布 npm 软件包和 GHCR 镜像；并按依赖顺序将工作区 crate 发布到 crates.io。随后，后续工作流 (publish-mcp-registry.yml) 会通过 GitHub OIDC 将此版本列入 MCP Registry。Linux GNU 二进制文件在 Ubuntu 22.04（glibc 2.35）上构建。Musl 目标暂缓支持，直到验证通过启用 clang 的 musl 构建器。

开发

cargo check          # workspace compile
cargo run -p nexql-mcp -- doctor
cargo test -p nexql-mcp -- init_clients
cargo fmt --all
cargo clippy --workspace --all-targets

实现前请阅读 CLAUDE.md 和 docs/REFERENCE.md。

许可证

从 v0.2.0 起，本仓库中的所有 crate 均采用 GPL-3.0-only 许可证。如果你分发此 程序或其衍生作品（包括捆绑在其他应用程序中的版本），也必须在 GPL 许可证下 发布源代码。

截至 v0.1.6（含）的版本均以 Apache-2.0 许可证发布。该授权对这些版本 不可撤销，且不受此变更影响。

版权仅由 NexQL-OSS Team 持有，因此可按需提供免除 GPL 义务的商业许可证。高级扩展（提供方嵌入、 团队同步、托管网关）位于单独的专有 crate 中。

路线图

完整计划：内部设计文档（federated-greeting-badger）。切换详情：docs/CUTOVER.md。

参考实现

同级 nexql-pro 检出目录中的 TypeScript 源码（聊天功能仍使用这些源码；MCP HTTP 栈已移除）：

• pro/src/mcp/McpDefinitionProvider.ts — 通过 stdio 启动此二进制文件
• pro/src/mcp/NexqlMcpStdioHost.ts — 临时配置文件 + 二进制解析
• pro/src/providers/chat/tools/ToolSpec.ts
• pro/src/providers/chat/tools/ToolExecutor.ts
• pro/src/features/dbindex/*