在 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 客户端
打开面板
- 打开一个 workspace。
- 在右侧侧边栏,点击 MCP 服务器 图标。
- 或使用 workspace 页脚(MCP 已启用 / MCP 已关闭),或命令面板(⌘K / CtrlK)并选择 打开 MCP 面板。
默认情况下,退出再打开 Kerry Studio 时,服务器不会再次启动。启动偏好在 设置 → MCP(面板 配置 标题上的齿轮图标,或命令面板 ⌘K / CtrlK → 设置:MCP):
- 应用启动时 → 启动时开启服务器:Kerry Studio 打开时启动 MCP 服务器(默认关闭)。
- 应用启动时 → 始终以只读模式启动:下次启动时回到只读,即使上一次会话是完整模式(默认打开)。
在面板里,齿轮旁边的 书本 图标打开文档(打开文档)。
配置 AI 客户端
- 在面板里打开 启用 MCP 服务器。
- 点击 复制 JSON。
- 把 JSON 贴进客户端的 MCP 设置(或合并进已经有的配置)。
- 如果客户端不会自己重新加载服务器,重启客户端。
如果客户端把 MCP 登记成本地二进制程序(例如 OpenCode),不要粘贴 JSON。使用 如何在 OpenCode 中使用 里的命令。
默认地址是 http://127.0.0.1:18765/mcp。面板里的 HTTP 端口 会改这个端口。服务器开启时,该字段锁定。复制 JSON 使用当前端口和真实令牌。不要使用示例里的 YOUR_TOKEN。
{
"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 中,面板里服务器已开启时,运行:
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 再贴进客户端一次。