Bring NeoSQL Desktop's database tools into your MCP host (Claude Code, Codex, Gemini CLI, Cursor, …) via npx.
Local stdio MCP server that connects MCP hosts to NeoSQL Desktop on macOS and Windows for PostgreSQL, Supabase, MySQL, MariaDB, Oracle, SQL Server, SQLite, H2, and Databricks.
2026-11-15
Sterne
—
Tools
—
Uptime
—
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.
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.
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.
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.
Host
Config file
Claude Code
.mcp.json in the project, or ~/.claude.json for the user
Codex
.codex/config.toml in the project, or ~/.codex/config.toml
Gemini CLI
.gemini/settings.json in the project, or ~/.gemini/settings.json
Cursor
.cursor/mcp.json in the project, or ~/.cursor/mcp.json
Claude Code, Gemini CLI, Cursor
These hosts share the same JSON shape under mcpServers:
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:
Replace <your-project-id> with the target project's ID, not its display name.
Without this option, tools use the project selected in Desktop. With it, an
app-dependent tool can switch the Desktop window to the requested project before
running. Connecting the MCP host, listing tools, or calling ping,
get-mcp-session-id, or get-context-help does not switch projects.
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
NeoSQL tools always use the project currently selected and fully loaded in NeoSQL
Desktop. With --project-id, the Node process retains the requested project ID for
navigation and project validation. Desktop still owns the active project and its
Default connection target.
Database tools accept a connection target in one of two forms:
Omit connectionId, database, and schema together to use the active project's
Default selected in NeoSQL MCP Access Control.
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
Tool
Target
Purpose
ping
Returns pong for a lightweight MCP health check.
get-mcp-session-id
Diagnostic tool that returns the upstream session id used by this process.
list-connections
Lists MCP-enabled NeoSQL connections and schemas for the current project.
get-context-help
Explains active-project Default and explicit target usage.
list-tables
Yes
Lists tables.
get-table-details
Yes
Returns columns, keys, indexes, and related table metadata.
erd-create-tables
Yes
Adds virtual tables to an ERD without changing the database.
erd-modify-tables
Yes
Modifies virtual ERD table models without changing the database.
execute-query
Yes
Executes SQL, including DDL.
generate-code
Yes
Generates and saves source files for specified tables using template packs configured in Project Settings. Requires template packs, required variables, and an output folder (Location). May overwrite existing files without an additional confirmation dialog.
Tools marked Target accept the connectionId, database, and schema fields
described in Context Resolution.
Transport
neosql-mcp talks to NeoSQL Desktop through a deterministic local endpoint:
macOS: neosql-mcp.sock in the per-user temp directory from getconf DARWIN_USER_TEMP_DIR
Windows: \\.\pipe\neosql-mcp
Troubleshooting
Desktop installation cannot be found
If Desktop is not installed, install it first. If it is already installed but detection
fails, open it manually and call the tool again. On macOS, neosql-mcp currently checks the standard
/Applications and ~/Applications locations first. If the app is not found there,
it falls back to the app path recorded by NeoSQL Desktop in
~/.neosql/mcp-config.json after the app has been launched at least once. On
Windows, it checks the per-user NSIS uninstall registry entry under HKCU.
Desktop does not start automatically
When Desktop is disconnected and its installation is detected, neosql-mcp requests
app activation once and waits for readiness. If installation checking or activation
fails, open Desktop manually, wait for it to load, and call the tool again.
Desktop does not respond or preparation times out
If preparation returns readiness_timeout, the 40-second preparation limit expired
before the operation was sent. Check Desktop for loading errors or pending prompts,
then retry once the project is ready. If the app is unresponsive, restart it.
If the operation was already sent and its response times out, it may have changed
data or files. Check the actual result before retrying; neosql-mcp does not
implicitly undo or automatically retry the operation.
Context-sensitive tools fail
Select a project in Desktop and enable MCP access for the connection and schema you intend to use.
Either configure a Default in MCP Access Control and omit all three target fields, or
run list-connections and pass its connectionId, databaseName, and schemaName
together as connectionId, database, and schema. The explicit form does not require
a Default. Use database: null when there is no database hierarchy; a partial target
is invalid.
If the response asks for sign-in or user action, complete the indicated step in
Desktop, such as unlocking the project, resolving a missing driver, or acknowledging
a notice. For a project load failure, resolve the error shown in Desktop before retrying.
npx cannot find or run the package
Check that the MCP host can access npx and that Node.js is 20 or later.
The configured project cannot be opened
Check the ID passed to --project-id and your access to that project in Desktop.
Save or discard unsaved changes, complete any sign-in or project notices, then retry.
If the active project changed during the request, return to the intended project
before trying again.
Local stdio MCP server that connects MCP hosts to NeoSQL Desktop on macOS and Windows for PostgreSQL, Supabase, MySQL, MariaDB, Oracle, SQL Server, SQLite, H2, and Databricks.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Neosql?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Neosql einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet Neosql?
Neosql läuft lokal über stdio.
Wann wurde Neosql zuletzt geprüft?
Zuletzt geprüft: 2026-11-15. Local stdio MCP server that connects MCP hosts to NeoSQL Desktop on macOS and Windows for PostgreSQL, Supabase, MySQL, MariaDB, Oracle, SQL Server, SQLite, H2, and Databricks.
