neosql-mcp
Summary: This MCP server exposes NeoSQL Desktop database and schema tools to MCP hosts via local stdio, letting clients inspect MCP-enabled connections, explore tables, run non-DDL SQL, manage table models, and generate code.
Health/diagnostics:
ping,getMcpSessionId, andgetContextHelp.Discover MCP-enabled database connections and schemas with
listConnections, including DBMS/version and per-schema policies.List tables/views in a schema, optionally filtering by search text.
Get detailed table metadata for one or more tables: columns, indexes, primary keys, and foreign keys.
Execute SQL with
executeQuery: SELECT, INSERT, UPDATE, DELETE, and EXPLAIN; DDL is rejected and SELECT/EXPLAIN return up to 200 rows.Create table definitions/models with columns, PKs, FKs, indexes, and constraints via
createTables; successful creations are added to the ERD.Modify existing table models/definitions via
modifyTables: renames, comments, PKs, columns, indexes, FKs, and constraints.Generate source code for a table using a configured template pack via
generateCode.Use current project/connection/schema context or explicit
connectionIdandschemavalues where supported.
Provides tools for interacting with Databricks databases through NeoSQL Desktop, including listing tables, retrieving table details, executing SQL queries, and creating or modifying tables.
Provides tools for interacting with MariaDB databases through NeoSQL Desktop, including listing tables, retrieving table details, executing SQL queries, and creating or modifying tables.
Provides tools for interacting with MySQL databases through NeoSQL Desktop, including listing tables, retrieving table details, executing SQL queries, and creating or modifying tables.
Provides tools for interacting with PostgreSQL databases through NeoSQL Desktop, including listing tables, retrieving table details, executing SQL queries, and creating or modifying tables.
Provides tools for interacting with SQLite databases through NeoSQL Desktop, including listing tables, retrieving table details, executing SQL queries, and creating or modifying tables.
Provides tools for interacting with Supabase databases through NeoSQL Desktop, including listing tables, retrieving table details, executing SQL queries, and creating or modifying tables.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@neosql-mcp list tables in the sales schema"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 DatabasesWhy 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.
Related MCP server: mssql-pyodbc-mcp
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-mcpThe 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 |
|
Codex |
|
Gemini CLI |
|
Cursor |
|
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@neosqlInside 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
Option | Default | Purpose |
| Not set | Open the specified project before an app-dependent tool runs and fail if the active project does not match it. |
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 <your-project-id> 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:
Omit
connectionId,database, andschematogether 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. Usedatabase: nullfor 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 |
| Returns | |
| Diagnostic tool that returns the upstream session id used by this process. | |
| Lists the projects you can open in Desktop. Works without an open project. | |
| Creates a local project with one design-only connection for a new design, after you approve it in Desktop. | |
| Lists MCP-enabled NeoSQL connections and schemas for the current project. | |
| Explains active-project Default and explicit target usage. | |
| Yes | Lists tables. |
| Yes | Returns columns, keys, indexes, and related table metadata. |
| Yes | Adds virtual tables to an ERD without changing the database. |
| Yes | Modifies virtual ERD table models without changing the database. |
| Yes | Executes SQL, including DDL. |
| 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. list-connections and every
Target tool also accept an optional projectId.
Transport
neosql-mcp talks to NeoSQL Desktop through a deterministic local endpoint:
macOS:
neosql-mcp.sockin the per-user temp directory fromgetconf DARWIN_USER_TEMP_DIRWindows:
\\.\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 NSIS uninstall registry entry under HKCU (per-user install), then HKLM
(per-machine install, used by NeoSQLEnterprise).
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, or pass a projectId from list-projects, 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.
Resources
Development
npm ci
npm run build
npm testTo test a local build from an MCP host, link the binary and unlink it when you are done:
npm run build
npm link
# ... test from your MCP host ...
npm unlink -g neosql-mcpAvailable Tools
10 toolscreateTablescreateTablesA
Create one or more new tables in the NeoSQL application. Pass multiple table definitions to create them in a single call. Each definition may include columns, primary keys, foreign keys, indexes, and table-level constraints (UNIQUE / CHECK / EXCLUSION). Tables that fail (e.g. duplicates) are skipped and reported; successfully created tables are added to the ERD. Uses the current context (project/connection).
Inputs: tableDefinitions (required), connectionId, schema.
executeQueryexecuteQueryA
Execute a SQL query on the database through NeoSQL. Supports SELECT, INSERT, UPDATE, DELETE, and EXPLAIN statements. DDL statements (CREATE, ALTER, DROP, TRUNCATE) are NOT allowed — use createTables or modifyTables tools instead. SELECT and EXPLAIN return result rows (up to 200 rows). Uses the current context (project/connection/schema).
Inputs: sql (required), connectionId, schema.
generateCodegenerateCodeB
Generate source code from a database table using a template pack. Uses the current context (project/connection/schema) for database connection. Returns generated file contents based on the specified template.
Inputs: tableName (required), templatePackId (required), schema.
getContextHelpgetContextHelpA
Get information about how to find project and connection IDs. NeoSQL project and connection information is managed by the NeoSQL application (UI). Use listConnections to discover MCP-enabled connectionId/schema pairs. Set stable defaults with CLI options and pass connectionId/schema per tool call when needed.
Inputs: no named parameters.
getMcpSessionIdgetMcpSessionIdD
Get Mcp-Session-Id
Inputs: no named parameters.
getTableDetailsgetTableDetailsA
Get detailed information about one or more tables including columns, indexes, primary keys, and foreign keys. Pass multiple table names to retrieve details in a single call. Uses the current context (project/connection/schema) if schema parameter is not specified.
Inputs: tableNames (required), connectionId, schema.
listConnectionslistConnectionsA
List database connections that have MCP access enabled in the current NeoSQL project. Only connections (and schemas) that the user opted-in via the connection MCP tab are returned. Use this to discover which connectionId / schema values you can pass to other tools. Each connection entry includes id, name, description, dataSource (DBMS family), dbVersion (database product version, useful for dialect-version features), the per-user profile (envPreset such as local/dev/staging/prod, label, protection), and the list of MCP-enabled schemas with their per-schema policies (ddlExecute / autoCommit).
Inputs: no named parameters.
listTableslistTablesA
List all tables and views in a database schema. Returns table names, types (TABLE/VIEW), and comments. Uses the current context (project/connection/schema) if parameters are not specified.
Inputs: connectionId, schema, search.
modifyTablesmodifyTablesA
Modify one or more existing tables in the NeoSQL application. Each alteration can include: table rename, comment operation, primary key operations, column operations (ADD/DROP/MODIFY/RENAME), index operations (ADD/DROP), foreign key operations (ADD/DROP), and table-level constraint operations (UNIQUE / CHECK / EXCLUSION; ADD/DROP). For table comments, use remarksOperation.modify=true when an empty string is an intended comment change. For primary keys, omit primaryKeyOperations or pass [] for no change; dropping every PK column requires an explicit DROP operation for each current PK column. Pass multiple alterations to modify several tables in a single call. Uses the current context (project/connection).
Inputs: alterations (required), connectionId, schema.
pingPingA
Health-check tool. Returns "pong".
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: schema creation, query execution, code generation, table details, listing, modification, connection discovery, context help, session ID, and health check. No overlapping responsibilities.
All tool names follow a consistent verbNoun camelCase pattern (createTables, executeQuery, generateCode, getTableDetails, listTables, modifyTables, listConnections, getContextHelp, getMcpSessionId, ping). No mixing of conventions.
10 tools is well-scoped for a database management server. It covers schema operations, query execution, discovery, and utility without being overwhelming.
Covers creation, modification, querying, and listing of tables, but lacks a drop table tool. Also missing is any tool for managing projects or connections beyond listing. This leaves notable gaps in lifecycle management.
Maintenance
Related MCP Connectors
The Instant MCP server is a wrapper around the Instant Platform SDK that enables creating, managing, and updating InstantDB applications directly within an editor. It provides tools for fetching rules files for LLMs, retrieving and pushing app schemas, managing permission rules, and executing database queries. Key capabilities include schema management (get-schema, push-schema), permission management (get-perms, push-perms), query execution, and listing recent query history.
Official Neon MCP server for managing Neon projects and Lakebase Postgres databases.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables SQL query execution and database structure browsing via MCP tools and resources.MIT
- FlicenseAqualityDmaintenanceLocal stdio MCP server for read-only Microsoft SQL Server access through Python and pyodbc, providing test connection, list tables, describe table, and query tools.4-
- AlicenseNot gradedqualityCmaintenanceMCP server that connects to SQL databases (SQLite, PostgreSQL, MSSQL, MySQL) and provides tools to run read-only queries, list schemas/tables, and manage connections via stdio transport.Apache 2.0
- AlicenseAqualityBmaintenanceEnables Oracle Database schema introspection and SQL execution over stdio, letting MCP hosts list tables, describe columns, and run SQL—read-only by default with opt-in writes.37 npmMIT