黑色星期五个人月付 15% 折扣。年付 5% 折扣 + 1 个礼遇席位。优惠有效期至 11 月 29 日。
本地 MCP 服务器

本地 MCP 服务器

在 Kerry Studio 中,本地 MCP 服务器把已保存的连接接到桌面 AI 客户端,例如 Claude Desktop、ChatGPT、Gemini、Conductor、Cursor、OpenCode 等。如果没有它,从对话里列出表、查看列或运行 SQL,就得手工粘贴 schema 或结果。

服务器只在你的计算机上监听。密码、SSH 和证书受应用保护。MCP 不会暴露它们。助手会收到项目、环境、数据库类型、数据库名、schema,以及它所运行查询的结果。Kerry 不会把这些内容发给 Sireeus 的服务器。助手能拿到什么是可配置的:服务器可以使用哪些项目和环境,以及要在 mcp.log 和回复中遮蔽哪些值。AI 客户端仍可能把 MCP 返回的内容发给它的云端模型。请只用于你信任的代理。

开始之前

需要:

  • Kerry Studio 里一个已打开的 workspace
  • 一个支持 MCP 的桌面 AI 客户端

打开面板

  1. 打开一个 workspace。
  2. 在右侧侧边栏,点击 MCP 服务器 图标。
  3. 或使用 workspace 页脚(MCP 已启用 / MCP 已关闭),或命令面板(⌘K / CtrlK)并选择 打开 MCP 面板。

默认情况下,退出再打开 Kerry Studio 时,服务器不会再次启动。启动偏好在 设置 → MCP(面板 配置 标题上的齿轮图标,或命令面板 ⌘K / CtrlK → 设置:MCP):

  • 应用启动时 → 启动时开启服务器:Kerry Studio 打开时启动 MCP 服务器(默认关闭)。
  • 应用启动时 → 始终以只读模式启动:下次启动时回到只读,即使上一次会话是完整模式(默认打开)。

在面板里,齿轮旁边的 书本 图标打开文档(打开文档)。

配置 AI 客户端

  1. 在面板里打开 启用 MCP 服务器。
  2. 点击 复制 JSON。
  3. 把 JSON 贴进客户端的 MCP 设置(或合并进已经有的配置)。
  4. 如果客户端不会自己重新加载服务器,重启客户端。

如果客户端把 MCP 登记成本地二进制程序(例如 OpenCode),不要粘贴 JSON。使用 如何在 OpenCode 中使用 里的命令。

默认地址是 http://127.0.0.1:18765/mcp。面板里的 HTTP 端口 会改这个端口。服务器开启时,该字段锁定。复制 JSON 使用当前端口和真实令牌。不要使用示例里的 YOUR_TOKEN。

json
{
  "mcpServers": {
    "kerry-studio": {
      "url": "http://127.0.0.1:18765/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

如何在 OpenCode 中使用

有些桌面 AI 客户端(例如 OpenCode)默认把 MCP 服务器登记成本地二进制程序。Kerry 不是这种服务器。它在你的计算机上通过 HTTP 监听。在这类应用里,用 URL 登记 Kerry,不要当成命令。

mcpServers 格式的 JSON 适用于粘贴配置的客户端。在 OpenCode 中,面板里服务器已开启时,运行:

bash
opencode mcp add kerry-studio --global --url http://127.0.0.1:18765/mcp --header 'Authorization=Bearer YOUR_TOKEN'

把 YOUR_TOKEN 换成 复制 JSON 写进 JSON 的令牌。如果你改过 HTTP 端口,URL 里用那个端口。--global 会让 Kerry 在所有 OpenCode 项目里可用。如果命令拒绝这个参数,说明你的版本没有它。去掉 --global 再运行同一条命令。

只读与完整模式

默认情况下服务器是 只读 的:助手可以列出连接、查看 schema,并运行只读查询:SELECT、SHOW、DESCRIBE、EXPLAIN(包括对 SELECT 的 ANALYZE)。INSERT、UPDATE、DELETE、SELECT … FOR UPDATE、SELECT INTO、INTO OUTFILE,以及会改数据的 WITH 查询会被拒绝。

只读已经会在助手的会话里打开数据库。没有这一步就没有 schema,也没有 SELECT。Kerry 的 SQL 标签页不必已经连接。

在面板里切换模式会立即生效,因此不必重启 Kerry Studio。

在 设置 → MCP → 只读 里,启动服务器时强制只读(默认打开)会让面板上的 只读模式 开关保持选中并锁定,并在服务器每次打开时应用只读。

权限

在 Kerry Studio 中,权限 限制本地 MCP 服务器可以使用哪些已保存的项目和环境。没有这项限制时,助手能用到每一条已保存的连接。默认是全部项目和环境。

只读与读取和写入各自有一份列表。因此你可以让只读看整个目录,而在完整模式里只放开其中几个项目。

从 MCP 面板的 配置、设置 → MCP,或命令面板(⌘K / CtrlK)里的 MCP 权限 打开 权限。

在 MCP 服务器权限 里,顶部在 只读 和 读取和写入 之间切换。正在使用 表示面板此刻在用哪一份:打开 只读模式 时,标记在 只读;关掉时,标记在 读取和写入。改一份不会改另一份。

在 读取和写入 列表里,默认写入 为列表设定插入、更新和删除,默认三种都打开。每个项目或连接都可以不同于该默认值。更改会在助手的下一次请求生效。

如果打开了 允许全部项目和环境,服务器会在该列表里使用整个目录。关掉它,就可以按项目挑选。

开关关掉后,每个项目以及该项目下的每个环境都有自己的控件。在 自动包含对以下项的访问 里,你可以决定 新项目及其当前环境 和 项目中的新环境 是否自动加入。搜索会按项目、SQL 别名(@alias)或环境缩小显示范围。全部启用 和 全部停用 只作用于当前可见的项。旁边的箭头把同样的操作应用到一个环境:在一个环境中全部启用 或 在一个环境中全部停用。

在面板上打开或关闭 只读模式 时,Kerry 会改用对应的那份列表。更改会在助手的下一次请求生效。如果项目不在这份列表里,Kerry 不会为助手打开该连接。带 @alias 的查询(例如 @billing.orders)会指向一条已保存的连接;该连接不可访问时,查询也会被阻止。

助手可以访问什么

连接错误不会返回用户名、主机、密码或文件路径。助手收到的 SQL 结果也会省去文件路径、主机、连接 URI 和密钥。Kerry 里的标签页网格保持原样。

连接列表显示项目、环境、数据库类型和数据库名(本地文件显示文件名,不显示路径)。

服务器打开时,助手还会收到:

  • 表名和视图名
  • 列和表的细节
  • 助手每次运行的 SQL 结果,最多 500 行
  • 对已打开 workspace 中 ER 图标签页的控制

控制 ER 图

在 Kerry Studio 中,助手可以像你一样使用 ER 图标签页。如果该项目和环境还没有标签页,它会打开一个;如果已经有,它会切过去。如果这个标签页尚未连接,使用图(同步、筛选、适配)会先连接并刷新 schema。助手只控制 ER 图标签页。打开、同步和切换环境都遵守 MCP 权限。它也可以筛选表、改布局、聚焦关系、调整缩放并导出图片。导出时,Kerry 把文件保存到 设置 → MCP 中的文件夹。默认为桌面。如果失败,Kerry 会询问保存位置。助手会收到完整路径。MCP 不能选择文件夹。

不带 @alias 的 SQL 仍在单独会话中运行,不会切换标签页。带 @alias 的 SQL,例如 @billing.orders,会使用当前的 SQL 标签页。

助手控制图的时候,标签页会显示 MCP 标记。workspace 页脚会显示 正在控制界面。

例子:

  • 「打开项目 billing、环境 开发 的 ER 图。」
  • 「在图里只显示与 public.orders 相关的表。」
  • 「把图适配到窗口,并导出为 PNG。」

在对话中如何提问

说出 项目 和 环境,不要只说技术上的连接标签(例如 postgres)。

例子:

  • 「在项目 billing、环境开发中,列出表」
  • 「在 Billing / 开发中,public.products 有哪些列?」

助手使用保存在 Kerry 里的连接。不带 @alias 的 SQL 在单独的会话里运行:它不会切换标签页,也不会切换 实体 侧边栏。带 @alias 的 SQL,例如 @billing.orders,使用当前的 SQL 标签页,与 执行查询 一样:@项目.表 跟随标签页的环境。当前标签页必须是 SQL,并且已关联到该项目和环境。只有已保存的项目会出现在 实体 里。

助手可以做什么

模式助手可以
只读列出连接,找到项目和环境,查看表和列,搜索 schema,运行只读 SQL,打开并控制 ER 图标签页
完整上面的全部,再加上 权限 中放开的写入 SQL(插入、更新和删除)

查看谁已连接

面板的 可观测性 一节列出正在和 Kerry 对话的应用。

  • 底部的数字是已连接的应用数量。
  • 每张卡片是一个应用。卡片上的数字是 那个 应用打开了多少条数据库会话。
  • 应用连接、断开,或开始查询数据库时会出现通知,即使面板是关着的。

要断开一个应用:点击卡片上的垃圾桶图标(断开连接)并确认。这会结束该应用的连接。如果另一个应用仍在使用同一数据库,它会留下。如果这是最后一个,Kerry 会关闭该数据库的 MCP 连接。

审计服务器

在 Kerry Studio 中,mcp.log 会记录与助手的每一次往来,并带上应用和会话。文件里的 REQUEST 是助手发出的请求,其中包括 SQL。RESPONSE 是 Kerry 返回的内容。在 MCP 面板的 可观测性 标题处或设置的 MCP 中打开该文件。

当字段名就是列表中的词或包含该词时,Kerry 会遮蔽该值。如果 SQL 给列起了别名、在表达式里用了该列,或从 JSON 里读取该字段并以另一个名字返回,同样会遮蔽。这适用于 PostgreSQL、MySQL、Oracle 和 SQLite。

默认会遮蔽:

  • 同时作用于文件和给助手的回复: 密码、令牌、授权和私钥的值,前提是字段匹配该目标的默认列表。
  • 仅作用于 mcp.log: 名称是或包含 email 的字段的值,以及正文里出现的电子邮箱,即使它们不是名为 email 的列。
  • 仅作用于给助手的回复: 连接字符串、密钥,以及会带出主机、用户、路径或密码的错误片段。这不取决于列名。

SQL 会写入 mcp.log,因为审计会按到达时的样子保存这次请求。用该文件检查你数据库里的某列是否仍以真实值出现在 RESPONSE 中。这适用于 Kerry 无法预先知道的字段,例如全名或证件号。如果仍出现,请在 MCP 面板的 已遮蔽的值 或命令面板(⌘K / CtrlK)中添加该字段,选择位置(文件、助手或两者),并选择匹配是精确还是包含。

关闭日志后,该选择会保留。如果文件已存在,Kerry 会先确认再删除。

故障排查

  • AI 客户端连不上 Kerry:确认 URL 使用的是 127.0.0.1,不是 localhost,并且端口与 HTTP 端口 一致。改端口后请再次 复制 JSON。
  • 粘贴 JSON 后客户端仍连不上:在面板里把服务器关掉再打开,或重启 AI 客户端。
  • OpenCode 连不上:Kerry 不是二进制 MCP。用带 --url 和 Authorization 头的 opencode mcp add。如果命令拒绝 --global,去掉这个参数。
  • 查询被拒绝:服务器处于只读模式,或该操作类型在 权限 中已关闭。如果这次写入是有意的,打开完整模式,并按 SQL 打开插入、更新或删除。SHOW 和对 SELECT 的 EXPLAIN 是读取。FOR UPDATE 和 SELECT INTO 不是。
  • 找不到数据库:按 项目和环境 来问(名称或 @alias),不要用连接标签。
  • 带 @alias 的 SQL 失败:聚焦已关联到该项目和环境的 SQL 标签页,与 执行查询 一样。
  • ER 图没有打开,或环境被拒绝:检查 权限,并指定该列表中的项目和环境。只有打开 workspace 时才有 MCP 面板。

如果在面板里重新生成了令牌,把 JSON 再贴进客户端一次。