Skip to main content
Glama
Sign In
enesjakoruzh
neosql-mcp

neosql-mcp

by unvus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

neosql-mcp

通过 npx 将 NeoSQL Desktop 的数据库工具引入你的 MCP 主机（Claude Code、Codex 等）。

npm version license node

neosql-mcp 是一个本地 stdio MCP 服务器，可让 MCP 主机通过 npx 使用 NeoSQL Desktop 工具。

它不是独立的数据库服务器、数据库 CLI，也不是 NeoSQL Desktop 的替代品。该包运行在 MCP 主机进程树内，通过标准 MCP stdio 暴露 NeoSQL 工具，并通过 macOS Unix Domain Socket 或 Windows Named Pipe 上的 HTTP JSON-RPC，将数据库/UI 工作委托给正在运行的 NeoSQL Desktop 应用。

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

为什么选择 neosql-mcp？

  • AI 编程助手在能够读取真实 schema 并运行真实查询时，会写出更好的代码，而不是猜测列名和表结构。neosql-mcp 将你的团队已在 NeoSQL Desktop 中配置好的数据库暴露给任何 MCP 主机。

  • 一个正在运行的 NeoSQL Desktop，一条 npx 命令——Claude Code、Codex 以及任何其他 MCP 主机都可以使用已在 NeoSQL Desktop 中配置的连接和 schema。无需逐主机配置，凭据永远不会离开 NeoSQL Desktop。

Related MCP server: mssql-pyodbc-mcp

安全性

所有流量都通过 Unix Domain Socket（macOS）或 Named Pipe（Windows）保留在本地机器上。不会打开任何 TCP 端口，且无法通过环境变量或配置文件覆盖上游端点。数据库访问范围遵循 NeoSQL Desktop 中的连接设置——凭据和每连接权限不会在此重复。

前提条件

  • Node.js 20 或更高版本。

  • 同一台机器上安装了 NeoSQL Desktop。

  • 一个能够启动 stdio 服务器的 MCP 主机，例如 Claude Code 或 Codex。

  • 一个启用了 MCP 的数据库连接和 schema 的 NeoSQL 项目。

快速开始

无需全局安装。配置你的 MCP 主机使用 npx 运行该包。

npx -y neosql-mcp

该进程是一个 stdio MCP 服务器，因此在终端中直接运行该命令时，可能会看起来像是在等待输入。这是正常现象。

MCP 主机配置

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

选项

描述

--profile=<prod|dev|local|stage>

连接到匹配的 NeoSQL Desktop 配置。

在 MCP 主机配置中使用 --key=value 形式。有意不支持诸如 --profile dev 之类的空格分隔形式。默认配置为 prod。

上下文解析

NeoSQL 工具始终使用当前在 NeoSQL Desktop 中选中并完全加载的项目。Node 进程不存储项目或默认数据库坐标。

数据库工具接受以下两种形式的坐标：

  1. 同时省略 connectionId、database 和 schema，以使用 NeoSQL MCP Access Control 中选定的活动项目 Default。

  2. 同时传入全部三个值，以使用 list-connections 返回的启用了 MCP 的显式坐标。对于没有数据库层次结构的 DBMS，使用 database: null。

仅传入一个或两个坐标字段是无效的。显式坐标在无效时永远不会回退到项目 Default。

接受完整显式坐标元组的工具：

  • list-tables

  • get-table-details

  • erd-create-tables

  • erd-modify-tables

  • execute-query

可用工具

工具

用途

ping

返回 pong，用于轻量级 MCP 健康检查。

get-mcp-session-id

诊断工具，返回此进程使用的上游会话 id。

list-connections

列出当前项目中启用了 MCP 的 NeoSQL 连接和 schema。

list-tables

使用项目 Default 或显式坐标列出表。

get-table-details

返回列、键、索引及相关表元数据。

get-context-help

说明活动项目 Default 和显式坐标的用法。

erd-create-tables

向 ERD 添加虚拟表，而不更改数据库。

erd-modify-tables

修改虚拟 ERD 表模型，而不更改数据库。

execute-query

使用 Default 或显式坐标执行 SQL，包括 DDL。

传输

neosql-mcp 通过确定性的本地端点与 NeoSQL Desktop 通信：

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

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

故障排除

NeoSQL Desktop was not found

请先安装 NeoSQL Desktop。在 macOS 上，neosql-mcp 目前会首先检查标准的 /Applications 和 ~/Applications 位置。如果在那里找不到应用，它会回退到 NeoSQL Desktop 在应用至少启动一次后记录在 ~/.neosql/mcp-config.json 中的应用路径。在 Windows 上，它会检查 HKCU 下按用户划分的 NSIS 卸载注册表项。

NeoSQL Desktop is not running

启动 NeoSQL Desktop，等待其完成加载，然后再次运行该工具。在可能的情况下，neosql-mcp 会在返回此状态之前请求操作系统级别的应用激活。

NeoSQL Desktop did not respond

应用可能仍在启动或被阻塞。稍等片刻后重试，或重启 NeoSQL Desktop。

上下文相关工具失败

在 NeoSQL Desktop 中选择一个项目，并在 MCP Access Control 中配置一个已启用的 Default。要使用其他坐标，请运行 list-connections，并将其 connectionId、databaseName 和 schemaName 值一起作为 connectionId、database 和 schema 传入。

npx 无法找到或运行该包

检查 MCP 主机是否可以访问 npx，以及 Node.js 是否为 20 或更高版本。

开发

npm ci
npm run build
npm test

要进行本地 MCP 主机测试，请构建并链接二进制文件：

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

本地测试完成后，取消链接，以便直接的 neosql-mcp 命令不再使用工作区构建：

npm unlink -g neosql-mcp

Available Tools

10 tools
createTablescreateTablesA

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.

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent verbNoun camelCase pattern (createTables, executeQuery, generateCode, getTableDetails, listTables, modifyTables, listConnections, getContextHelp, getMcpSessionId, ping). No mixing of conventions.

    Tool Count5/5

    10 tools is well-scoped for a database management server. It covers schema operations, query execution, discovery, and utility without being overwhelming.

    Completeness3/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mssql-pyodbc-mcp

      tsod
      F
      license
      A
      quality
      D
      maintenance
      Local 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
      -

    • SQL Database Bridge

      alizaimovic
      A
      license
      Not graded
      quality
      C
      maintenance
      MCP 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

    • Raw SQL MCP

      KifoPL
      A
      license
      Not graded
      quality
      C
      maintenance
      Raw SQL MCP is a STDIO MCP server for executing raw SQL against SQL Server, SQLite, PostgreSQL, MySQL, and MariaDB.
      AGPL 3.0