NexQL Postgres MCP

nexql-mcp

スタンドアロンの Postgres MCP サーバー — スキーマを認識し、デフォルトで読み取り専用、あらゆる環境にインストールできます。

NexQL Pro には、VS Code 専用のインプロセス MCP サーバーが含まれています（pro/src/mcp/）。このリポジトリではその機能を独立した Rust バイナリとして切り出し、Claude Desktop、Cursor、VS Code Copilot、Zed など、あらゆる MCP クライアントから起動できるようにしています。

ステータス： フェーズ 0〜6、フェーズ 7 拡張機能の切り替え（stdio 起動）、フェーズ 8 HTTP（ベアラートークン、セッション、レート制限）、フェーズ 9 書き込み／管理ツールを実装済みです。スキーマ、クエリ、コンテキスト、パフォーマンス、書き込み、管理の各領域にまたがる 54 個のツールを備えています。完全な OAuth ゲートウェイは引き続き Pro 専用です。セッションストアの LRU 追い出し上限はまだ実装されていません。docs/CUTOVER.md をご覧ください。

開発の背景

競合する Postgres MCP サーバーが公開するのは、「接続 → クエリ実行 → 行を返す」という機能です。モデルは、実在しないスキーマに対してテーブル名を幻覚します。NexQL の強みは、pro/src/features/dbindex/ で構築されるオフラインのスキーマインデックスです（TF-IDF、推論した FK を含む結合グラフ、値プロファイル、オプションの埋め込み、RRF 融合）。このリポジトリでは、そのインデックスに加え、Pro のクエリ／スキーマ／DBA／メタデータ用ツール 54 個を高速で簡単にインストールできるバイナリに移植しています。

アーキテクチャ

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 エージェントが代わりに実行する場合も同じように動作します。Node.js が必要です（npx は Node.js に同梱されています）。それ以外は必要ありません。

# 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 コーディングエージェントとして、ユーザーに代わってこの設定を行う場合： 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 に出力されます）。claude mcp add 形式のシェルコマンドを手書きしたり、クライアントの 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 で設定）です。エージェントのコンテキストウィンドウに読み込まれるツールスキーマ 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. Settings → NexQL: Mcp: Enabled（postgresExplorer.mcp.enabled）を検索し、チェックを入れます。デフォルトではオフです。
2. 以上です。設定はすぐに反映され（再読み込みは不要）、postgresExplorer.connections に保存済みのすべての接続が読み込まれます。Copilot Chat／エージェントモードのツール選択画面に、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 終了。接続先がほかに解決されない場合、URL もフラグも指定せずに nexql-mcp を実行すると、TUI が自動的に起動します。

リリース

v* タグをプッシュすると .github/workflows/release.yml が起動し、 darwin arm64/x64、linux gnu arm64/x64、windows x64 向けにビルドします。アーカイブ、プラットフォームごとの .mcpb バンドル、 CycloneDX SBOM、レンダリング済みの Homebrew formula を GitHub リリースに添付し、npm パッケージと GHCR イメージを公開します。また、依存関係の順序に従ってワークスペースのクレートを 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 以降 GPL-3.0-only です。この プログラムまたはその派生物を、別のアプリケーションに同梱する場合も含めて配布する場合は、 ソースコードも GPL に基づいて公開する必要があります。

v0.1.6 までのリリースは Apache-2.0 の下で公開されました。この許諾は これらのバージョンについて取り消し不能であり、今回の変更の影響を受けません。

著作権は NexQL-OSS Team のみに帰属するため、GPL の義務を免除する商用ライセンスは ご要望に応じて提供しています。プレミアム拡張機能（プロバイダー埋め込み、 チーム同期、ホスト型ゲートウェイ）は、別のプロプライエタリクレートで提供しています。

ロードマップ

全体計画：社内設計ドキュメント（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/*