neosql-mcp

Bring NeoSQL Desktop's database tools into your MCP host (Claude Code, Codex, …) 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.

[MCP host] -- stdio MCP --> [neosql-mcp]
  -- JSON-RPC over HTTP on UDS/Named Pipe --> [NeoSQL Desktop]

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, and any other MCP host can use the connections and schemas already configured in NeoSQL Desktop. No per-host setup, and credentials never leave NeoSQL Desktop.

Related MCP server: database-remote-mcp

Security

All traffic stays on the local machine over a Unix Domain Socket (macOS) or Named Pipe (Windows). No TCP ports are opened, and the upstream endpoint cannot be overridden by environment variables or config files. Database access scope follows the connection settings in NeoSQL Desktop — credentials and per-connection permissions are not duplicated here.

Prerequisites

• Node.js 20 or later.

• NeoSQL Desktop installed on the same machine.

• An MCP host that can launch stdio servers, such as Claude Code or Codex.

• 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

Claude Code .mcp.json

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

Codex config.toml

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

CLI Options

Use the --key=value form in MCP host config. Space-separated forms such as --profile dev are intentionally not supported. The default profile is prod.

Context Resolution

NeoSQL tools always use the project currently selected and fully loaded in NeoSQL Desktop. The Node process does not store a project or default database coordinate.

Database tools accept coordinates 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 coordinate returned by list-connections. Use database: null for DBMSs without a database hierarchy.

Passing only one or two coordinate fields is invalid. Explicit coordinates never fall back to the project Default when they are invalid.

Tools that accept the complete explicit coordinate tuple:

• list-tables

• get-table-details

• execute-query

• create-tables

• modify-tables

Available Tools

Transport

neosql-mcp talks to NeoSQL Desktop through a deterministic local endpoint:

• macOS: path.join(os.tmpdir(), 'neosql-mcp.sock')

• Windows: \\.\pipe\neosql-mcp

Troubleshooting

NeoSQL Desktop was not found

Install NeoSQL Desktop first. 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.

NeoSQL Desktop is not running

Start NeoSQL Desktop, wait for it to finish loading, and run the tool again. When possible, neosql-mcp requests OS-level app activation before returning this state.

NeoSQL Desktop did not respond

The app may still be starting or blocked. Wait a moment and retry, or restart NeoSQL Desktop.

Context-sensitive tools fail

Select a project in NeoSQL Desktop and configure an enabled Default in MCP Access Control. To use another coordinate, run list-connections and pass its connectionId, databaseName, and schemaName values together as connectionId, database, and schema.

npx cannot find or run the package

Check that the MCP host can access npx and that Node.js is 20 or later.

Development

npm ci
npm run build
npm test

For local MCP host testing, build and link the binary:

npm run build
npm link
ls -la $(which neosql-mcp)

When local testing is done, unlink it so direct neosql-mcp commands no longer use the workspace build:

npm unlink -g neosql-mcp