adb-mcp的8个常见问题一次搞定:完整故障排查清单(代理未启动、插件连不上、字体缺失)

adb-mcp是一个让 AI 直接操控 Adobe 软件的开源工具：通过 MCP 协议连接 Claude 等 AI 助手与 Photoshop、Premiere Pro、InDesign、After Effects、Illustrator，实现"用自然语言指挥设计软件"。新手搭建时最容易踩的坑集中在三类：MCP 服务启动失败、插件连不上代理、字体缺失。本文把这些问题整理成一份可直接对照的完整故障排查清单，每个问题都给出"现象 → 原因 → 解决步骤"，看完即可快速定位并修复。

先看懂架构：为什么问题会出在这三个环节？

adb-mcp 的通信链路是：

AI 客户端 ↔ MCP 服务（Python）↔ 命令代理服务器（Node，端口 3001）↔ Adobe 应用内插件 ↔ Photoshop / Premiere

链路中任何一环断了，AI 都会"失联"。下面 8 个问题就是按这条链路逐一排查的。

问题1：MCP 服务在 Claude 中启动失败

现象：重启 Claude Desktop 后，MCP 工具列表里没有 adb-mcp，或提示 MCP 无法工作。

常见原因：Claude 的配置文件里uv命令使用了相对路径，Claude 以不同工作目录启动时就找不到命令。

解决步骤：

1. 打开 Claude 的配置文件，找到 MCP 配置项；
2. 将uv命令改为绝对路径（例如C:\Users\你\...\uv.exe或/usr/local/bin/uv）；
3. 保存后重启 Claude Desktop。

安装时参考 README.md 中的uv run mcp install ...命令，依赖清单见 requirements.txt。

问题2：代理服务器没有启动（最高频故障）

现象：AI 回复时长时间卡住，或提示无法连接 Photoshop / Premiere。

原因：adb-mcp 依赖一个独立的 Node 代理服务器中转命令，它必须全程保持运行，很多用户装完就把它关了。

解决步骤：

1. 进入 adb-proxy-socket/ 目录，运行node proxy.js（推荐方式是从 Release 下载对应平台的预编译可执行文件）；
2. 看到adb-mcp Command proxy server running on ws://localhost:3001即为启动成功，见 proxy.js；
3. 使用期间不要关闭该窗口，代理一停，整条链路全断。

问题3：插件安装失败 / 加载不出 MCP Agent 面板

现象：在 UXP Developer Tools 里 Load 插件报错，或应用里找不到 MCP Agent 面板。

解决步骤：

1. 确保先启动对应的 Adobe 应用（Photoshop 需 26.0 及以上），再去 Load 插件；
2. Photoshop 需先在Settings > Plugins中勾选Enable Developer Mode并重启；
3. 在 UXP Developer Tools 中选择File > Add Plugin，指向各应用的 manifest.json（如uxp/ps/manifest.json、uxp/pr/manifest.json、uxp/id/manifest.json）；
4. After Effects / Illustrator 走 CEP 扩展目录（符号链接方式），详见 README.md。

问题4：插件点 Connect 后一直连不上代理

现象：插件面板的按钮点了一次后仍显示 "Connect"（连上后会变成 "Disconnect"）。

原因：插件默认连接http://localhost:3001（见 main.js），连不上基本只有两种可能——代理没启动，或 3001 端口被防火墙/安全软件拦截。

解决步骤：

1. 回到问题2确认代理服务正在运行；
2. 检查防火墙是否放行本地 3001 端口；
3. 在 UXP Developer Tools 中点击 Load 旁边的Debug按钮（或打开 Developer Workspace 查看控制台），具体报错一目了然；
4. 连接成功时，代理窗口会打印User connected与registered for application: photoshop字样。

问题5：重启 Adobe 应用后，AI 突然"失忆"

现象：一切正常，重启了 Photoshop / Premiere，AI 再操作就全部失败。

原因：UXP 插件在应用重启后不会自动加载，必须手动重新 Load。

解决步骤：每次重启 Adobe 应用后，打开 UXP Developer Tools，重新点击对应插件的Load按钮，再在应用内点Connect。把这条写进你的使用习惯即可。

问题6：AI 提示字体缺失 / 字体列表不全

现象：让 AI 使用某个字体时提示找不到，或字体列表里"缺了很多字体"。

原因：MCP 服务出于数据量考虑，默认只按字母顺序返回前 1000 个PostScript 字体名（见 ps-mcp.py 中的FONT_LIMIT = 1000，扫描逻辑在 fonts.py）。

解决步骤：

1. 不必追求"列表里有"，直接用字体的PostScript 名称告诉 AI 即可（可以顺口问 AI 该字体对应的 PostScript 名）；
2. 如果系统根本没装该字体，先到系统字体目录安装。

问题7：AI 执行命令报错、操作失败

现象：AI 返回错误，或执行到一半失败。

排查顺序：

1. 先查链路：插件是否显示已连接？代理服务是否还在运行？（90% 的报错是这两个原因）；
2. 点击聊天中的命令/代码框，可以看到具体的错误信息，AI 通常也会直接说明问题；
3. 响应特别慢时：确认 AI 服务端不繁忙，并避免当前对话过长——新开一个会话往往能明显提速（但会丢失上下文）。

问题8：AI 频繁"乱操作"，结果不符合预期

现象：功能链路完全正常，但 AI 总用错工具、参数不对，返工率高。

原因：没有加载官方提供的get_instructions说明资源，AI 缺少对可用 API 和注意事项的"背景知识"。

解决步骤：在 Claude 的输入框点击"+"，选择Add from Adobe Photoshop（或 Premiere）→config://get_instructions，发送后等 AI 消化完再开始干活，可显著减少出错。

附加建议：AI 工作期间不要手动改动设计文件；如有改动务必告诉 AI。

8个问题速查表

更多细节可参考项目自带的 Troubleshooting 章节。照着这份清单从上到下过一遍，adb-mcp 的绝大多数故障都能一次搞定 🎯