claude-code-desktop-sync

# claude-code-desktop-sync 让 **Claude 代码** 和 **Claude 桌面版** 保持同步。在一个应用中添加或更改 MCP 服务器，另一应用会自动镜像，无需手动复制粘贴，也不会出现配置漂移。对于无法同步的内容（硬件平台限制），该工具会提供确切的手动步骤，而不是静默失败。 它可以安装在 **纯净版** Claude 代码 和 Claude 桌面版 设置上，与现有配置合并（永远不会覆盖），在每次更改前备份，并且完全可逆。 ## 功能 - ✅ **双向自动同步 stdio MCP 服务器**，在 `~/.claude.json` （代码）和 Claude 桌面版 的配置文件之间。相对启动器（如 `npx`）会重写为桌面版的绝对路径（桌面版没有 shell `PATH`）。 - ⚠️ **检测 HTTP / header-auth MCP 服务器** （例如，PAT 身份验证的 `github` 连接器），这些服务器 **无法** 存在于桌面版配置文件中，并打印一次性手动步骤（桌面版 → 连接器 UI）。 - ❌ **清楚地记录无法同步的内容** — 技能、内存、设置、扩展和会话/对话存储在两个应用不共享的单独存储中。 通过 Claude 代码的 **SessionStart 钩子** 自动运行，除非有变化，否则保持沉默。 > **为什么不是所有内容？** Claude 桌面版是一个独立的应用，不读取 Claude 代码的文件、钩子或内存。只有两个应用都读取的配置文件中的配置（MCP 服务器列表）才能自动同步。有关完整矩阵和原因，请参见 [`docs/SYNC-REFERENCE.md`](docs/SYNC-REFERENCE.md)。 ## 要求 - 已安装 Claude 代码 和/或 Claude 桌面版 （如果只安装了一个，同步操作将为空操作）。 - **Python 3.8+** （仅标准库，无 pip 安装）。插件钩子运行 `python3`，因此它必须在 `PATH` 上（在 macOS/Linux 和 Windows 上使用 Microsoft Store Python）。在 Windows 上使用 python.org Python（安装 `python`/`py`，而不是 `python3`），请使用独立的 `install.py` — 它解析您拥有的解释器并将绝对路径写入钩子中。 - macOS、Windows 或 Linux。 ## 安装 ### 选项 A — 作为 Claude 代码插件（推荐） 该仓库是一个 Claude 代码插件 和 其自身的单一插件市场。从 Claude 代码内部： ```bash /plugin marketplace add haiggoh/claude-code-desktop-sync /plugin install claude-code-desktop-sync@haiggoh ``` 就这样 — 插件自己注册 `SessionStart` 钩子（无需复制文件到您的 `settings.json`）并附带一个伴侣技能。重启 Claude 代码（和 Claude 桌面版，如果已打开），以便每个应用重新加载其配置。 ### 选项 B — 独立安装（无插件系统） 如果您想直接将钩子写入您自己的配置： ```bash git clone https://github.com/haiggoh/claude-code-desktop-sync.git cd claude-code-desktop-sync python3 install.py # 或：python3 install.py --dry-run ``` 独立安装程序： 1. 将引擎复制到 `~/.claude/desktop-sync/sync_code_desktop.py`。 2. 将 `SessionStart` 钩子添加到 `~/.claude/settings.json` （合并到任何现有的钩子中）。 3. 将标记边界的指令块添加到 `~/.claude/CLAUDE.md`，以便 Claude 代码会话了解同步规则并始终显示手动步骤。 4. 运行初始同步。 重启 Claude 代码（和 Claude 桌面版，如果已打开），以便每个应用重新加载其配置。 ## 伴侣技能 插件捆绑了一个模型调用的技能，`desktop-sync`，用于按需帮助 — 现在运行同步、检查正在同步的内容或排查缺少的服务器。可以使用 `/claude-code-desktop-sync:desktop-sync` 调用它，或直接用自然语言询问 Claude（例如，“将我的 MCP 服务器同步到桌面版” / “为什么我的 github 连接器不在桌面版中？”），它会自动加载。 ## 用法 安装后，无需执行任何操作 — 它将在每个代码会话开始时运行。要按需同步： - **插件安装（选项 A）：** 请 Claude “将我的 MCP 服务器同步到桌面版”，或调用伴侣技能 `/claude-code-desktop-sync:desktop-sync`。引擎位于版本化的插件缓存中（例如 `~/.claude/plugins/cache/haiggoh/claude-code-desktop-sync/<version>/bin/sync_code_desktop.py`），因此不要硬编码其路径 — 技能为您解析它。 - **独立安装（选项 B）：** 直接运行复制的引擎： ```bash python3 ~/.claude/desktop-sync/sync_code_desktop.py ``` 当您在代码中添加了一个服务器时的示例输出： ``` [claude-sync] 更新了 Claude 桌面版配置 （备份：~/.claude/desktop-sync/backups/claude_desktop_config.json.20260701-183531.bak） + 添加到桌面版：my-new-server ``` ## 冲突处理 协调 **按服务器和基于内容** （每个侧面的最后同步值的快照），而不是基于时间戳。对于每个服务器：一个侧面的更改被传播到另一个侧面；添加被镜像；删除（存在于快照中，现在消失）被镜像。如果 **同一服务器在两侧发生了不同的更改**，则是一个 **冲突**：两侧 **都不受影响** 并按名称报告，供您解决 — 不会静默覆盖。名称在一個應用中是_stdio_服务器，在另一个应用中是 HTTP/connector，同样会被保留并报告（因此连接器及其令牌永远不会被覆盖）。在第一次运行期间，只有一侧存在服务器会被添加到另一侧（一个安全的联合 — 不会删除任何内容）。 ## 安全 - 在写入文件之前备份每个文件（时间戳下，`~/.claude/desktop-sync/backups/`；模式 `600`，因为 `~/.claude.json` 可能保存纯文本令牌）。 - 仅更改 `mcpServers` 块 — 所有其他键和值都保留（文件被重新序列化，带有 2 个空格的缩进和 `ensure_ascii=False`，因此值被保留，但原始空白/格式被规范化）。 - 钩子永远不会引发异常：如果发生任何错误，它会干净地退出，因此它不会阻止会话启动。 ## 卸载 ```bash python3 uninstall.py # 删除钩子 + CLAUDE.md 块 python3 uninstall.py --purge # 还要删除 ~/.claude/desktop-sync ``` ## 工作原理 有关配置位置、完整同步矩阵、冲突规则和备份/恢复过程，请参见 [`docs/SYNC-REFERENCE.md`](docs/SYNC-REFERENCE.md)。 ## 许可证 MIT — 请参见 [LICENSE](LICENSE)。 --- *与 Anthropic 无关。“Claude” 是 Anthropic 的商标。这是社区工具。*