NeoSQL MCP

neosql-mcp

英語 | 한국어

npxを介してNeoSQL DesktopのデータベースツールをMCPホスト（Claude Code、Codex、Gemini CLI、Cursor、…）で利用できます。

neosql-mcpは、npxを介してMCPホストからNeoSQL Desktopのツールを利用できる、ローカルのstdio MCP サーバーです。

スタンドアロンのデータベースサーバー、データベース CLI、またはNeoSQL Desktopの代替ではありません。このパッケージはMCPホストのプロセスツリー内で実行され、標準のMCP stdioを介してNeoSQLツールを公開します。また、macOSのUnix Domain SocketまたはWindowsのNamed Pipe上のHTTP経由のJSON-RPCを通じて、実行中のNeoSQL DesktopアプリにデータベースやUI関連の処理を委譲します。

+-------------------+    +-------------------+    +-------------------+
|                   |    |                   |    |                   |
|  Claude Code      +--->+                   +--->+  NeoSQL Desktop   |
|                   |    |                   |    |                   |
|                   |    |                   |    +---------+---------+
|  Codex            |    |                   |              |
|                   |    |                   |              v
|                   |    |                   |    +-------------------+
|  Gemini CLI       |    |     neosql-mcp    |    |                   |
|                   |    |                   |    |  PostgreSQL       |
|                   |    |                   |    |  MySQL            |
|  Cursor           |    |                   |    |  MariaDB          |
|                   |    |                   |    |  Oracle           |
|                   |    |                   |    |  SQL Server       |
|  Other MCP hosts  |    |                   |    |  ... and more     |
|                   |    |                   |    |                   |
+-------------------+    +-------------------+    +-------------------+
     MCP hosts             stdio MCP server            Databases

neosql-mcpを選ぶ理由

• AIコーディングアシスタントは、列名やテーブルの構造を推測するのではなく、実際のスキーマを読み取り、実際のクエリを実行できると、より適切なコードを作成できます。neosql-mcpは、チームがすでにNeoSQL Desktopで設定しているデータベースを、任意のMCPホストに公開します。
• 実行中のNeoSQL Desktopが1つあれば、npxコマンド1つで利用できます。Claude Code、Codex、Gemini CLI、Cursor、その他のMCPホストから、NeoSQL Desktopで設定済みの接続とスキーマを使用できます。データベース接続は、MCPホストごとに個別に設定するのではなく、Desktopで設定します。

対応データベース

PostgreSQL、Supabase、MySQL、MariaDB、Oracle、SQL Server、SQLite、H2、Databricks。

データベースへの接続はNeoSQL Desktopが行うため、neosql-mcpはDesktopがサポートするすべてのDBMSで動作します。バージョン要件とDBMSごとの接続方法については、DBMS接続ガイドを参照してください。

セキュリティ

neosql-mcpとNeoSQL Desktop間の通信は、Unix Domain Socket（macOS）またはNamed Pipe（Windows）を介してローカルマシン上で行われます。このチャネルはTCPポートを開かず、エンドポイントを環境変数や設定ファイルで上書きすることもできません。データベースへのアクセスはDesktopのMCPアクセス制御設定に従います。MCPホストの設定にデータベースの認証情報は必要ありません。

スキーマ情報とクエリ結果はMCPホストに返されます。ホストによるそのデータの取り扱いと、Desktopのデータベース接続は、このローカル通信の境界の対象外です。execute-queryはDDLを含むSQLを実行でき、generate-codeはファイルを書き込むことができます。使用前に、要求された操作とDesktopのアクセス設定を確認してください。

データの処理、保存、保持、削除の詳細については、NeoSQL MCPプライバシーポリシーを参照してください。

前提条件

• macOSまたはWindows。
• Node.js 20以降。
• 同じマシンにNeoSQL Desktopがインストールされていること。
• Claude Code、Codex、Gemini CLI、Cursorなど、stdioサーバーを起動できるMCPホスト。
• MCP対応のデータベース接続とスキーマを含むNeoSQLプロジェクト。

クイックスタート

グローバルインストールは不要です。MCPホストがnpxでパッケージを実行するように設定してください。

npx -y neosql-mcp

このプロセスはstdio MCPサーバーなので、ターミナルで直接コマンドを実行すると、入力待ちのように見える場合があります。これは正常な動作です。

MCPホストの設定

neosql-mcpはClaude Code、Codex、Gemini CLI、Cursorでテスト済みです。stdioサーバーを起動できるMCPホストであれば、同じコマンドと引数を使用できます。

ホスト	設定ファイル
Claude Code	プロジェクト内の.mcp.json、またはユーザー用の~/.claude.json
Codex	プロジェクト内の.codex/config.toml、または~/.codex/config.toml
Gemini CLI	プロジェクト内の.gemini/settings.json、または~/.gemini/settings.json
Cursor	プロジェクト内の.cursor/mcp.json、または~/.cursor/mcp.json

Claude Code、Gemini CLI、Cursor

これらのホストでは、mcpServers 内で同じ JSON 形式を使用します。

{
  "mcpServers": {
    "neosql": {
      "command": "npx",
      "args": ["-y", "neosql-mcp"]
    }
  }
}

Codex

[mcp_servers.neosql]
command = "npx"
args = [
  "-y",
  "neosql-mcp",
]

Claude プラグインとしてインストールする

Claude Code と Claude Desktop Cowork では、上記の手動による mcpServers エントリーの代わりに、neosql-mcp をプラグインとして読み込むこともできます。このプラグインはバージョンを固定したパッケージを実行するため、新しいバージョンはローカルの npx キャッシュに依存せず、プラグインの更新によって利用できるようになります。

Claude ディレクトリから

claude.ai または Claude デスクトップアプリで、カスタマイズ › プラグイン › 検索を開き、NeoSQL MCPを検索して、追加を選択します。プラグインは claude.ai アカウントに保存され、そのアカウントにサインインした状態で次回 Claude Code のセッションを開始すると、Claude Code 2.1.273 以降で neosql-mcp@synced として読み込まれます。Claude Chat はこのローカル MCP サーバーを実行しません。

このリポジトリのマーケットプレイスから

claude.ai にログインせずに Claude Code を使用する場合や、ターミナルまたはスクリプトからインストールする場合は、このリポジトリをプラグインマーケットプレイスとして追加し、そこからプラグインをインストールします。

claude plugin marketplace add unvus/neosql-mcp
claude plugin install neosql-mcp@neosql

セッション内で /plugin install neosql-mcp --marketplace unvus/neosql-mcp を実行すると、両方の手順が完了します。マーケットプレイスのプラグインはデフォルトでは自動更新されません。claude plugin update neosql-mcp@neosql を実行するか、/plugin で neosql マーケットプレイスの自動更新を有効にしてください。

手動設定でプラグインを使用する

Claude Code では、手動の neosql エントリーとプラグインは別々のサーバーとして扱われるため、両方を有効にすると各ツールが二重に表示されます。/mcp で有効なサーバーを確認し、どちらか一方を無効にしてください。--project-id でプロジェクトを固定する場合は、手動設定を維持し、.claude/settings.local.json でそのリポジトリのプラグインを無効にしてください。ディレクトリからインストールした場合は neosql-mcp@synced、マーケットプレイスからインストールした場合は neosql-mcp@neosql を使用します。

{
  "enabledPlugins": {
    "neosql-mcp@synced": false
  }
}

CLI オプション

オプション	デフォルト	用途
--project-id=<id> または --project-id <id>	未設定	アプリに依存するツールの実行前に指定したプロジェクトを開き、アクティブなプロジェクトが一致しない場合は失敗させます。

特定のプロジェクトを対象にするには、そのプロジェクト ID を MCP ホストの引数に追加します。

"args": ["-y", "neosql-mcp", "--project-id=<your-project-id>"]

<your-project-id> は、表示名ではなく、対象プロジェクトの ID に置き換えてください。 このオプションを指定しない場合、ツールは Desktop で選択されているプロジェクトを使用します。指定した場合、アプリに依存するツールは実行前に Desktop のウィンドウを要求されたプロジェクトに切り替えることができます。MCP ホストへの接続、ツールの一覧表示、または ping、get-mcp-session-id、get-context-help の呼び出しでは、プロジェクトは切り替わりません。

移動を妨げる未保存の変更がある場合は、Desktop で保存するか破棄してください。サインイン、プロジェクトへのアクセス、その他の必要な確認は、引き続き Desktop で処理されます。 準備中にプロジェクトが変更された場合、または Desktop がリクエストを確認した時点で一致しなくなった場合、別のプロジェクトを黙って使用するのではなく、操作は失敗します。 プロジェクト指定に対応したバージョンの Desktop を使用してください。

デスクトップの準備状況

アプリに依存するツールの実行前に、neosql-mcp は現在の Desktop とプロジェクトの状態を確認します。macOS と Windows では、Desktop がインストール済みでも接続されていない場合、アプリのアクティブ化を一度リクエストし、共有の40秒の時間枠内で準備が整うまで待機します。アプリのアクティブ化、任意のプロジェクトへの移動、プロジェクトの読み込みには、同じ準備時間枠が適用されます。プロジェクトの準備が整うと、元の操作が同じツール呼び出し内で一度実行されます。ユーザーの操作が必要な場合は、返された案内に従って Desktop で操作し、その後ツールを再度呼び出してください。

進行状況トークンを提供する MCP ホストには、英語の進行状況通知が送信されます。トークンがない場合も、準備の動作は同じです。ホストでの表示と全体のタイムアウトは、ホストによって制御されます。準備をキャンセルすると、すでに起動した Desktop アプリは実行中のまま、以降の確認と操作の送信が停止します。準備エラーの場合は、status、message、nextAction、requestSent: false を含む JSON テキストとともに isError: true が返されます。送信済みの操作は従来の結果形式を維持し、自動的に再送されることはありません。

コンテキストの解決

NeoSQL ツールは常に、NeoSQL Desktop で現在選択され、完全に読み込まれたプロジェクトを使用します。--project-id を指定すると、Node プロセスは移動とプロジェクトの検証に使用する、指定されたプロジェクト ID を保持します。アクティブなプロジェクトとその Default 接続先は、引き続き Desktop が管理します。

データベースツールでは、接続先を次のいずれかの形式で指定します。

1. connectionId、database、schema をまとめて省略し、NeoSQL MCP Access Control で選択したアクティブなプロジェクトの Default を使用します。
2. 3つすべての値を指定し、list-connections が返す MCP 対応の明示的な接続先を使用します。データベース階層のない DBMS では、database: null を使用します。

これらのフィールドのうち、1つまたは2つだけを指定することはできません。明示的な接続先が無効な場合、プロジェクトの Default へのフォールバックは行われません。

明示的な接続先を指定できるツールには、利用可能なツール で印が付いています。

利用可能なツール

ツール	対象	目的
ping		軽量な MCP ヘルスチェックとして pong を返します。
get-mcp-session-id		このプロセスが使用する上流セッション ID を返す診断ツールです。
list-connections		現在のプロジェクトで MCP が有効な NeoSQL の接続とスキーマを一覧表示します。
get-context-help		アクティブなプロジェクトの Default と明示的な対象の使用方法を説明します。
list-tables	はい	テーブルを一覧表示します。
get-table-details	はい	列、キー、インデックス、および関連するテーブルのメタデータを返します。
erd-create-tables	はい	データベースを変更せずに、ERD に仮想テーブルを追加します。
erd-modify-tables	はい	データベースを変更せずに、仮想 ERD テーブルモデルを変更します。
execute-query	はい	DDL を含む SQL を実行します。
generate-code	はい	Project Settings で設定されたテンプレートパックを使用して、指定されたテーブルのソースファイルを生成し、保存します。テンプレートパック、必須変数、および出力フォルダー（Location）が必要です。追加の確認ダイアログなしで既存ファイルを上書きする場合があります。

対象とマークされたツールは、コンテキストの解決で説明されている connectionId、database、および schema フィールドを受け取ります。

トランスポート

neosql-mcp は、決定論的なローカルエンドポイントを通じて NeoSQL Desktop と通信します。

• macOS：getconf DARWIN_USER_TEMP_DIR で取得したユーザーごとの一時ディレクトリ内の neosql-mcp.sock
• Windows：\\.\pipe\neosql-mcp

トラブルシューティング

Desktop が見つからない

Desktop がインストールされていない場合は、まずインストールしてください。すでにインストールされているのに検出に失敗する場合は、手動で起動してから、もう一度ツールを呼び出してください。macOS では、neosql-mcp は現在、標準の /Applications および ~/Applications の場所を最初に確認します。そこにアプリが見つからない場合は、アプリを少なくとも一度起動した後に NeoSQL Desktop が ~/.neosql/mcp-config.json に記録したアプリのパスを確認します。Windows では、HKCU のユーザーごとの NSIS アンインストールレジストリエントリを確認します。

Desktop が自動的に起動しない

Desktop が切断されていて、インストールが検出されている場合、neosql-mcp はアプリのアクティベーションを一度要求し、準備が整うまで待機します。インストールの確認またはアクティベーションに失敗した場合は、Desktop を手動で起動し、読み込みが完了するまで待ってから、もう一度ツールを呼び出してください。

Desktop が応答しない、または準備がタイムアウトする

準備処理が readiness_timeout を返した場合、操作が送信される前に40秒の準備時間制限を超過しています。Desktop に読み込みエラーや保留中のプロンプトがないか確認し、プロジェクトの準備が整ってから再試行してください。アプリが応答しない場合は、再起動してください。

操作がすでに送信されていて、その応答がタイムアウトした場合、データやファイルが変更されている可能性があります。再試行する前に実際の結果を確認してください。neosql-mcp は、暗黙的に操作を取り消したり、自動的に再試行したりしません。

コンテキスト依存ツールが失敗する

Desktop でプロジェクトを選択し、使用する接続とスキーマの MCP アクセスを有効にしてください。MCP Access Control で Default を設定して3つのターゲットフィールドをすべて省略するか、list-connections を実行し、返された connectionId、databaseName、schemaName をそれぞれ connectionId、database、schema として渡してください。明示的な指定方法では Default は不要です。データベース階層がない場合は database: null を使用してください。一部のみを指定したターゲットは無効です。

応答でサインインまたはユーザー操作を求められた場合は、プロジェクトのロック解除、不足しているドライバーの解決、通知の確認など、Desktop に表示された手順を完了してください。プロジェクトの読み込みに失敗した場合は、再試行する前に Desktop に表示されたエラーを解決してください。

npx でパッケージが見つからない、または実行できない

MCP ホストが npx にアクセスできることと、Node.js のバージョンが20以上であることを確認してください。

設定したプロジェクトを開けない

--project-id に渡した ID と、Desktop でそのプロジェクトにアクセスできることを確認してください。保存していない変更を保存または破棄し、サインインやプロジェクトに関する通知に対応してから再試行してください。リクエスト中にアクティブなプロジェクトが変わった場合は、再試行する前に目的のプロジェクトに戻してください。

リソース

• NeoSQL のウェブサイト
• NeoSQL MCP ドキュメント
• NeoSQL Desktop のインストール
• 対応 DBMS と接続ガイド
• NeoSQL MCP プライバシーポリシー

開発

npm ci
npm run build
npm test

MCP ホストからローカルビルドをテストするには、バイナリをリンクし、完了したらリンクを解除してください。

npm run build
npm link
# ... test from your MCP host ...
npm unlink -g neosql-mcp