NeoSQL MCP

neosql-mcp

English | 한국어

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

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

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

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

为什么选择 neosql-mcp？

• AI 编码助手如果能够读取真实的架构并运行真实查询，而不是猜测列名和表结构，就能编写出更好的代码。neosql-mcp 可将团队已在 NeoSQL Desktop 中配置的数据库提供给任何 MCP 主机。
• 只需运行一个 NeoSQL Desktop，执行一条 npx 命令，即可让 Claude Code、Codex、Gemini CLI、Cursor 和其他 MCP 主机使用 NeoSQL Desktop 中已配置的连接和架构。数据库连接在 Desktop 中配置，无需为每个 MCP 主机分别配置。

支持的数据库

PostgreSQL、Supabase、MySQL、MariaDB、Oracle、SQL Server、SQLite、H2 和 Databricks。

数据库连接由 NeoSQL Desktop 建立，因此 neosql-mcp 适用于 Desktop 支持的所有 DBMS。有关版本要求和各 DBMS 的连接详情，请参阅 DBMS 连接指南。

安全性

neosql-mcp 与 NeoSQL Desktop 之间的通信通过 Unix Domain Socket（macOS）或 Named Pipe（Windows）在本地计算机上进行。此通道不会开放 TCP 端口，其端点也无法通过环境变量或配置文件覆盖。数据库访问遵循 Desktop 的 MCP 访问控制设置；MCP 主机配置无需数据库凭据。

架构信息和查询结果会返回给 MCP 主机。主机如何处理这些数据，以及 Desktop 的数据库连接，均不在此本地传输边界的保护范围内。execute-query 可以执行包括 DDL 在内的 SQL，generate-code 可以写入文件；使用前请检查请求执行的操作和 Desktop 访问设置。

有关数据处理、存储、保留和删除的详情，请参阅 NeoSQL MCP 隐私政策。

前置条件

• macOS 或 Windows。
• Node.js 20 或更高版本。
• 在同一台计算机上安装 NeoSQL Desktop。
• 能够启动 stdio 服务的 MCP 主机，例如 Claude Code、Codex、Gemini CLI 或 Cursor。
• 一个配置了启用 MCP 的数据库连接和架构的 NeoSQL 项目。

快速开始

无需全局安装。将 MCP 主机配置为通过 npx 运行此软件包。

npx -y neosql-mcp

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

MCP 主机配置

neosql-mcp 已在 Claude Code、Codex、Gemini CLI 和 Cursor 中测试。任何能够启动 stdio 服务的 MCP 主机都可以使用相同的命令和参数。

主机	配置文件
Claude Code	项目中的 .mcp.json，或用户目录中的 ~/.claude.json
Codex	项目中的 .codex/config.toml，或 ~/.codex/config.toml
Gemini CLI	项目中的 .gemini/settings.json，或 ~/.gemini/settings.json
Cursor	项目中的 .cursor/mcp.json，或 ~/.cursor/mcp.json

Claude Code、Gemini CLI、Cursor

这些宿主在 mcpServers 下使用相同的 JSON 结构：

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

Codex

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

作为 Claude 插件安装

Claude Code 和 Claude Desktop Cowork 也可以将 neosql-mcp 作为插件加载，而不是使用上面的手动 mcpServers 条目。该插件运行固定版本的软件包，因此新版本会随插件更新提供，而不依赖本地 npx 缓存。

从 Claude 目录安装

在 claude.ai 或 Claude 桌面应用中，打开 自定义 › 插件 › 发现，搜索 NeoSQL MCP，然后选择 添加。该插件会保存到你的 claude.ai 帐户，并在你下次使用该帐户登录并启动会话时，以 neosql-mcp@synced 的形式加载到 Claude Code 中（Claude Code 2.1.273 或更高版本）。Claude Chat 不会运行此本地 MCP 服务。

从此代码库中的市场安装

如果你在未登录 claude.ai 的情况下使用 Claude Code，或者想从终端或脚本安装，请将此代码库添加为插件市场，然后从中安装插件：

claude plugin marketplace add unvus/neosql-mcp
claude plugin install neosql-mcp@neosql

在会话中，/plugin install neosql-mcp --marketplace unvus/neosql-mcp 会完成这两个步骤。默认情况下，市场插件不会自动更新；请运行 claude plugin update neosql-mcp@neosql，或在 /plugin 中为 neosql 市场启用自动更新。

将插件与手动配置搭配使用

在 Claude Code 中，手动的 neosql 条目和插件是两个独立的服务，因此同时保留两者会使每个工具都显示两次。查看 /mcp 以确认哪些服务处于活动状态，并禁用其中一个。若要使用 --project-id 固定项目，请保留手动配置，并在该代码库的 .claude/settings.local.json 中禁用插件；目录安装使用 neosql-mcp@synced，市场安装使用 neosql-mcp@neosql：

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

CLI 选项

选项	默认值	用途
--project-id=<id> 或 --project-id <id>	未设置	在依赖应用的工具运行前打开指定项目；如果当前项目与指定项目不匹配，则失败。

若要指定特定项目，请将其项目 ID 添加到 MCP 宿主的参数中：

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

将 <your-project-id> 替换为目标项目的 ID，而不是其显示名称。 如果不使用此选项，工具会使用 Desktop 中选定的项目。使用此选项后，依赖应用的工具可以在运行前将 Desktop 窗口切换到请求的项目。连接 MCP 宿主、列出工具，或调用 ping、 get-mcp-session-id 或 get-context-help，都不会切换项目。

如果未保存的更改阻止导航，请在 Desktop 中保存或放弃这些更改。登录、项目访问和其他必要确认仍由 Desktop 处理。 如果在准备期间项目发生变化，或者 Desktop 检查请求时项目已不再匹配，操作将失败，而不会悄悄使用其他项目。 请使用支持指定项目的 Desktop 版本。

桌面就绪状态

依赖应用的工具运行前，neosql-mcp 会检查当前桌面应用和项目状态。在 macOS 和 Windows 上，如果已安装桌面应用但未连接，它会请求激活应用一次，并在共享的 40 秒时限内等待就绪。应用激活、可选的项目导航和项目加载共用此准备时限。项目就绪后，原始操作会在同一次工具调用中运行一次。如果需要用户操作，请按照返回的指导在桌面应用中操作，然后再次调用该工具。

提供进度令牌的 MCP 主机会收到英文进度通知。没有令牌时，就绪流程仍以相同方式运行。主机负责控制显示方式和总体超时。取消准备流程会停止后续检查和操作提交，但已启动的桌面应用会继续运行。准备错误会返回 isError: true，并附带包含 status、message、nextAction 和 requestSent: false 的 JSON 文本。已提交的操作会保留原有结果格式，且绝不会自动重新发送。

上下文解析

NeoSQL 工具始终使用 NeoSQL 桌面应用中当前选定且已完全加载的项目。使用 --project-id 时，Node 进程会保留所请求的项目 ID，以供导航和项目验证使用。活动项目及其默认连接目标仍由桌面应用管理。

数据库工具接受以下两种形式之一的连接目标：

1. 将 connectionId、database 和 schema 一并省略，以使用 NeoSQL MCP 访问控制中为活动项目选定的默认连接目标。
2. 一并传入这三个值，以使用 list-connections 返回的已启用 MCP 的目标。对于没有数据库层级的 DBMS，请使用 database: null。

只传入其中一个或两个字段无效。显式目标无效时，绝不会回退到项目默认目标。

接受显式连接目标的工具会在可用工具中标注。

可用工具

工具	目标	用途
ping		返回 pong，用于轻量级 MCP 健康检查。
get-mcp-session-id		诊断工具，返回此进程使用的上游会话 ID。
list-connections		列出当前项目中启用了 MCP 的 NeoSQL 连接和架构。
get-context-help		说明活动项目的 Default 和显式目标用法。
list-tables	是	列出表。
get-table-details	是	返回列、键、索引和相关表元数据。
erd-create-tables	是	在 ERD 中添加虚拟表，不更改数据库。
erd-modify-tables	是	修改虚拟 ERD 表模型，不更改数据库。
execute-query	是	执行 SQL，包括 DDL。
generate-code	是	使用 Project Settings 中配置的模板包，为指定表生成并保存源文件。需要模板包、必需变量和输出文件夹（Location）。可能会在没有额外确认对话框的情况下覆盖现有文件。

标记为 目标 的工具接受 上下文解析 中所述的 connectionId、database 和 schema 字段。

传输

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

• macOS：getconf DARWIN_USER_TEMP_DIR 返回的每用户临时目录中的 neosql-mcp.sock
• Windows：\\.\pipe\neosql-mcp

故障排除

找不到桌面应用安装位置

如果尚未安装 Desktop，请先安装。如果已安装但检测失败，请手动打开，然后再次调用工具。在 macOS 上，neosql-mcp 目前会优先检查标准的 /Applications 和 ~/Applications 位置。如果在这些位置找不到应用， 则会回退到应用至少启动过一次后，NeoSQL Desktop 在 ~/.neosql/mcp-config.json 中记录的应用路径。在 Windows 上，它会检查 HKCU 下针对当前用户的 NSIS 卸载注册表项。

Desktop 不会自动启动

当 Desktop 已断开连接且检测到已安装时，neosql-mcp 会请求激活应用一次并等待其就绪。如果安装检查或激活失败，请手动打开 Desktop，等待其加载完成，然后再次调用工具。

Desktop 无响应或准备超时

如果准备过程返回 readiness_timeout，说明在发送操作之前，40 秒的准备时限已过。检查 Desktop 是否存在加载错误或待处理的提示，然后等项目就绪后重试。如果应用无响应，请重启应用。

如果操作已经发送，但响应超时，它可能已经更改了数据或文件。重试前请检查实际结果；neosql-mcp 不会隐式撤销操作，也不会自动重试。

与上下文相关的工具失败

在 Desktop 中选择一个项目，并为你打算使用的连接和架构启用 MCP 访问权限。 你可以在 MCP 访问控制中配置默认值，并省略全部三个目标字段；也可以运行 list-connections，并将其 connectionId、databaseName 和 schemaName 分别作为 connectionId、database 和 schema 一起传入。显式指定目标时不需要默认值。没有数据库层级时，请使用 database: null；只指定部分目标无效。

如果响应要求登录或用户操作，请在 Desktop 中完成所指示的步骤，例如解锁项目、解决缺少驱动程序的问题，或确认通知。如果项目加载失败，请先解决 Desktop 中显示的错误，再重试。

npx 无法找到或运行该软件包

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

无法打开配置的项目

检查传递给 --project-id 的 ID，以及你在 Desktop 中访问该项目的权限。保存或放弃未保存的更改，完成任何登录或项目通知要求，然后重试。如果请求期间当前项目发生变化，请先切回目标项目，再重试。

资源

• NeoSQL 网站
• NeoSQL MCP 文档
• 安装 NeoSQL Desktop
• 支持的 DBMS 和连接指南
• NeoSQL MCP 隐私政策

开发

npm ci
npm run build
npm test

要通过 MCP 主机测试本地构建，请链接该二进制文件，并在完成后取消链接：

npm run build
npm link
# ... test from your MCP host ...
npm unlink -g neosql-mcp