NeoSQL MCP

neosql-mcp

English | 한국어

Bring NeoSQL Desktop's database tools into your MCP host (Claude Code, Codex, Gemini CLI, Cursor, …) via npx.

neosql-mcp is a local stdio MCP server that lets MCP hosts use NeoSQL Desktop tools through npx.

It is not a standalone database server, database CLI, or replacement for NeoSQL Desktop. The package runs inside the MCP host process tree, exposes NeoSQL tools over standard MCP stdio, and delegates database/UI work to a running NeoSQL Desktop app through JSON-RPC over HTTP on a macOS Unix Domain Socket or Windows Named Pipe.

+-------------------+    +-------------------+    +-------------------+

| | | | | | | 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

Why neosql-mcp?

• AI coding assistants write better code when they can read your real schema and run real queries, instead of guessing column names and table shapes. neosql-mcp exposes the database your team already configured in NeoSQL Desktop to any MCP host.
• One running NeoSQL Desktop, one npx command — Claude Code, Codex, Gemini CLI, Cursor, and any other MCP host can use the connections and schemas already configured in NeoSQL Desktop. Database connections are configured in Desktop rather than separately for each MCP host.

Supported Databases

PostgreSQL, Supabase, MySQL, MariaDB, Oracle, SQL Server, SQLite, H2, and Databricks.

Database connections are made by NeoSQL Desktop, so neosql-mcp works with every DBMS that Desktop supports. See the DBMS connection guide for version requirements and per-DBMS connection details.

Security

Communication between neosql-mcp and NeoSQL Desktop stays on the local machine over a Unix Domain Socket (macOS) or Named Pipe (Windows). This channel opens no TCP ports, and its endpoint cannot be overridden by environment variables or config files. Database access follows Desktop's MCP Access Control settings; MCP host configuration does not require database credentials.

Schema information and query results are returned to your MCP host. The host's handling of that data and Desktop's database connections are outside this local transport boundary. execute-query can execute SQL including DDL, and generate-code can write files; review the requested operations and Desktop access settings before use.

See the NeoSQL MCP Privacy Policy for data processing, storage, retention, and deletion details.

Prerequisites

• macOS or Windows.
• Node.js 20 or later.
• NeoSQL Desktop installed on the same machine.
• An MCP host that can launch stdio servers, such as Claude Code, Codex, Gemini CLI, or Cursor.
• A NeoSQL project with MCP-enabled database connections and schemas.

Quick Start

No global install is required. Configure your MCP host to run the package with npx.

npx -y neosql-mcp

The process is a stdio MCP server, so running the command directly in a terminal may look like it is waiting for input. That is expected.

MCP Host Configuration

neosql-mcp has been tested with Claude Code, Codex, Gemini CLI, and Cursor. Any MCP host that can launch a stdio server can use the same command and arguments.

Claude Code, Gemini CLI, Cursor

These hosts share the same JSON shape under mcpServers:

{

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

Codex

[mcp_servers.neosql]

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

Install as a Claude Plugin

Claude Code and Claude Desktop Cowork can also load neosql-mcp as a plugin instead of the manual mcpServers entry above. The plugin runs a version-pinned package, so new versions arrive with plugin updates rather than depending on the local npx cache.

From the Claude directory

In claude.ai or the Claude desktop app, open Customize › Plugins › Discover, search for NeoSQL MCP, and select Add. The plugin is saved to your claude.ai account and loads in Claude Code as neosql-mcp@synced the next time you start a session signed in to that account (Claude Code 2.1.273 or later). Claude Chat does not run this local MCP server.

From the marketplace in this repository

If you use Claude Code without a claude.ai login, or want to install from a terminal or a script, add this repository as a plugin marketplace and install the plugin from it:

claude plugin marketplace add unvus/neosql-mcp

claude plugin install neosql-mcp@neosql

Inside a session, /plugin install neosql-mcp --marketplace unvus/neosql-mcp does both steps. Marketplace plugins do not auto-update by default; run claude plugin update neosql-mcp@neosql, or enable auto-update for the neosql marketplace in /plugin.

Using the plugin with a manual configuration

A manual neosql entry and the plugin are separate servers in Claude Code, so keeping both shows every tool twice. Check /mcp to see which servers are active and disable one of them. To pin a project with --project-id, keep the manual configuration and disable the plugin for that repository in .claude/settings.local.json, using neosql-mcp@synced for a directory install or neosql-mcp@neosql for a marketplace install:

{

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

CLI Options

To target a specific project, add its project ID to the MCP host's arguments:

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

Replace with the target project's ID, not its display name. Without this option, tools use the projectId passed to the tool, or the project selected in Desktop. With it, an app-dependent tool can switch the Desktop window to the requested project before running; a tool call with a different projectId is rejected, and create-project is unavailable. Connecting the MCP host, listing tools, or calling ping, get-mcp-session-id, get-context-help, list-projects, or create-project does not switch to the configured project.

Save or discard unsaved changes in Desktop if they prevent navigation. Sign-in, project access, and other required confirmations are still handled in Desktop. If the project changes during preparation, or no longer matches when Desktop checks the request, the operation fails instead of silently using another project. Use a Desktop version that supports project targeting.

Desktop Readiness

Before an app-dependent tool runs, neosql-mcp checks the current Desktop and project state. On macOS and Windows, if Desktop is installed but disconnected, it requests app activation once and waits for readiness within a shared 40-second budget. App activation, optional project navigation, and project loading share this preparation budget. Once the project is ready, the original operation runs once in the same tool call. If user action is required, follow the returned guidance in Desktop and call the tool again afterward.

MCP hosts that provide a progress token receive English progress notifications. Without a token, readiness works the same way. Host display and overall timeouts are controlled by the host. Cancelling preparation stops further checks and operation submission while leaving an already launched Desktop app running. Preparation errors return isError: true with JSON text containing status, message, nextAction, and requestSent: false. Operations already submitted keep their existing result format and are never automatically resent.

Context Resolution

Each NeoSQL tool call works on one project: the projectId passed to the tool, else the project set with --project-id, else the project currently open in NeoSQL Desktop. When the target is not open, Desktop opens it first, and the tool runs once the project is fully loaded. Desktop still owns the active project and its Default connection target.

If no project is open and none is configured, call list-projects and pass the chosen projectId. To start a new design, call create-project: after you approve it in Desktop, it creates a local project with one design-only connection set as the Default and opens it. Pass the returned projectId to later tools such as erd-create-tables. If the host sends a cancellation while the creation confirmation is pending, it is forwarded to Desktop to close the dialog. Cancellation does not roll back a project whose creation has already started; check list-projects before retrying.

Database tools accept a connection target in one of two forms:

1. Omit connectionId, database, and schema together to use the active project's Default selected in NeoSQL MCP Access Control.
2. Pass all three values together to use an explicit MCP-enabled target returned by list-connections. Use database: null for DBMSs without a database hierarchy.

Passing only one or two of these fields is invalid. An explicit target never falls back to the project Default when it is invalid.

Tools that accept an explicit connection target are marked in Available Tools.

Available Tools