STARWARCLOUD STARWAR.AI
返回市场
同步MCP

同步MCP

作者：richblack8 星标更新：2025-11-02
安装使用来源：spider==github.com

项目介绍

SyncMCP - MCP配置同步工具 🚀

版本 Python 许可证

智能MCP（模型上下文协议）配置同步工具，轻松管理多个AI客户端配置。

🤖 100%由Claude开发，持续进化

✨ 功能

  • 🔄 智能同步 -自动选择最新配置并一键同步所有客户端
  • 💾 自动备份 -每次同步前自动备份，安全无忧
  • 🎨 交互界面 -友好终端UI，即使是非技术人员也能轻松使用
  • 🤖 MCP服务器 -作为MCP服务器，让Claude帮助你管理配置
  • 🌍 全局命令 -安装后可在任何位置执行
  • 🔍 差异检测 -智能分析配置差异，提供清晰报告
  • 🛡️ 错误回滚 -同步失败时自动恢复备份

📖 目录

问题与解决方案

问题

每个AI代理（Claude Desktop、Claude Code、Roo Code、Gemini CLI）都有自己的MCP服务器配置文件。当你在客户端上安装或修改MCP时，其他客户端不会自动同步，导致：

  • ❌ 配置不一致
  • ❌ 需要手动复制配置
  • ❌ 容易出错且繁琐
  • ❌ 无法追踪配置变更历史

解决方案

SyncMCP提供：

  • ✅ 自动选择最新配置版本
  • ✅ 智能处理不同客户端之间的格式差异
  • ✅ 自动备份所有更改并支持一键恢复
  • ✅ 同步到所有客户端
  • ✅ 检测配置丢失并发出警告
  • ✅ 友好的交互界面

🚀 快速开始

安装

SyncMCP支持两种安装方式，选择适合你的：

🎯 方法1：uvx（推荐给初学者和单次使用）

无需安装，直接执行：

# 检查系统
uvx syncmcp doctor

# 查看状态
uvx syncmcp status

# 执行同步
uvx syncmcp sync

优点无需安装，自动隔离，速度更快

📦 方法2：pip（推荐频繁使用）

# 安装
pip install syncmcp

# 使用
syncmcp doctor
syncmcp status
syncmcp sync

优点命令更短，适合日常使用

🔧 方法3：从源码安装（开发者）

git clone https://github.com/yourusername/syncmcp.git
cd syncmcp
pip install -e .

五分钟入门

# 1. 检查系统是否正常
syncmcp doctor

# 2. 查看当前配置状态
syncmcp status

# 3. 预览同步（不实际修改）
syncmcp sync --dry-run

# 4. 执行同步
syncmcp sync

# 5. （可选）使用互动模式
syncmcp interactive

支持的客户端

客户端特性对比

特性Claude CodeRoo CodeClaude DesktopGemini CLI
配置层次
全局配置✅✅✅✅
项目级别配置✅✅❌❌
传输类型
stdio (本地)✅✅✅✅
sse (远程)✅⚠️ 未测试❌⚠️ 未测试
http (远程)✅⚠️ 需转换为 streamable-http❌⚠️ 未测试
特殊类型
streamable-http❌✅ 仅Roo独有❌❌

类型转换规则

SyncMCP自动处理不同客户端之间的格式差异：

同步方向转换规则描述
Roo Code → Claude Codestreamable-http → sse 或 http根据是否有headers决定
Claude Code → Roo Codesse/http → streamable-http统一转换为Roo格式
任意 → Claude Desktop过滤掉所有 http/sse 类型Desktop仅支持stdio
任意 → Gemini仅同步全局配置Gemini不支持项目级别

⚠️ 重要通知：

  • Claude Code 中出现的 streamable-http 表示同步错误
  • 在Roo Code中 http 必须是 streamable-http
  • Claude Desktop 无法使用远程MCP（http/sse）

配置文件位置

客户端配置文件路径
Claude Code~/.claude.json
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Roo Code~/.roo-code/config.json
Gemini CLI~/.gemini/config.json

💎 主要功能

1. 智能同步

自动选择最新配置并同步到所有客户端。

# 自动同步
syncmcp sync

# 预览模式（不实际修改）
syncmcp sync --dry-run

# 手动确认每个变更
syncmcp sync --strategy manual

# 同步但不建立备份
syncmcp sync --no-backup

同步期间会做什么：

  • 加载所有客户端配置
  • 自动选择最新配置作为来源
  • 分析配置差异
  • 自动转换不兼容格式
  • 建立备份
  • 执行同步
  • 记录历史

2. 配置可见性

查看所有客户端的状态和MCP列表。

# 查看所有客户端状态
syncmcp status

# 列出所有 MCP
syncmcp list

# 查看配置差异
syncmcp diff

# 打开配置文件
syncmcp open claude-code

3. 自动备份和恢复

所有更改都会自动备份，并支持一键恢复。

# 查看同步历史
syncmcp history

# 查看统计信息
syncmcp history --stats

# 互动式恢复备份
syncmcp restore

# 查看最近20条历史
syncmcp history --limit 20

备份特性：

  • 自动保留最新的10个备份
  • 每个备份都包含所有客户端配置
  • 时间戳标记，易于识别
  • 一键恢复

4. 系统诊断

全面的系统健康检查。

syncmcp doctor

检查项：

  • ✅ Python版本（>=3.10）
  • ✅ syncmcp命令是否在PATH中
  • ✅ 必要依赖套件
  • ✅ MCP支持检测
  • ✅ 配置文件位置
  • ✅ 目录结构
  • ✅ 提供修复建议

5. 交互界面（TUI）

友好的终端菜单界面。

syncmcp interactive

功能：

  • 🔄 交互同步 - 预览更改 -> 确认 -> 执行
  • 📊 配置状态 - 表格显示所有客户端
  • 🔍 差异分析 - 颜色标注变化
  • 📜 同步历史 - 查看过去记录
  • ⏮️ 恢复备份 - 从历史备份恢复

操作方法：

  • ↑/↓ 选择选项
  • Enter 确认
  • Ctrl+C 退出

6. MCP服务器集成

让AI可以直接调用SyncMCP功能。

可用工具：

  • sync_mcp_configs - 同步配置
  • check_sync_status - 检查状态
  • show_config_diff - 显示差异
  • suggest_conflict_resolution - 建议解决方案

使用示例：

您: "帮我同步所有MCP配置"
Claude: [自动执行同步并报告结果]

您: "列出所有客户端的MCP列表"
Claude: [显示详细的配置状态]

使用方法

基本使用

# 查看帮助
syncmcp --help

# 查看版本
syncmcp --version

# 执行同步
syncmcp sync

# 查看状态
syncmcp status

常见场景

场景1：添加MCP后同步

# 在Claude Code安装MCP
cd ~
claude mcp add github npx @modelcontextprotocol/server-github

# 同步到其他客户端
syncmcp sync

场景2：测试新MCP后回滚

# 安装并测试新MCP
claude mcp add test-mcp npx test-mcp-server
syncmcp sync

# 发现问题，恢复到之前状态
syncmcp restore
# 选择同步前的备份

场景3：查看配置差异

# 查看所有客户端的配置差异
syncmcp diff

# 预览同步会做什么
syncmcp sync --dry-run

更多示例，请参阅 EXAMPLES.md

📚 文档

请参阅完整的文档以获取详细信息 docs/ 目录

⚠️ 常见问题

1. syncmcp命令未找到

原因：安装后未加入PATH

解决方案：

# 检查安装
pip list | grep syncmcp

# 重新安装
pip install --force-reinstall syncmcp

# 使用doctor检查
python3 -m syncmcp doctor

2. Python版本太旧

症状：Python 3.9.0 (需要 >= 3.10)

解决方案：

# macOS
brew install python@3.12

# Ubuntu/Debian
sudo apt install python3.12

3. 项目级别MCP未同步（Bug #13）

症状：MCP存在于Claude Code但syncmcp看不到它

原因：目前不支持项目级别的MCP

解决方案：将MCP移动到全局级别

# 在项目目录中删除
cd /path/to/project
claude mcp remove mcp-name

# 切换到非项目目录
cd ~

# 重新添加到全局
claude mcp add mcp-name npx mcp-server

# 同步
syncmcp sync

详细描述：docs/MOVE-MCP-TO-GLOBAL.md

4. Claude Desktop HTTP MCP无法同步

原因：Claude Desktop 仅支持 stdio 类型

解决方案：这是正常行为，SyncMCP会自动过滤掉不支持的类型。

5. 同步失败

检查步骤：

# 1. 执行诊断
syncmcp doctor

# 2. 查看详细错误
syncmcp sync --verbose

# 3. 检查配置文件权限
ls -la ~/.claude.json

# 4. 从备份恢复
syncmcp restore

更多故障排除，请参阅 USER-GUIDE.md

🗺️ 功能状态

✅ v2.0 完成（当前版本）

  • [x] 核心功能

    • [x] 智能配置同步
    • [x] 自动类型转换（http/sse/streamable http）
    • [x] 差异检测引擎
    • [x] 自动备份和恢复
    • [x] 配置验证

  • [x] 用户界面

    • [x] 完整CLI工具（10+命令）
    • [x] 交互风格TUI
    • [x] 丰富的颜色输出
    • [x] 系统诊断工具

  • [x] 开发者工具

    • [x] MCP服务器集成（4个工具）
    • [x] 完整测试套件（92个测试）
    • [x] CI/CD流水线
    • [x] 提交前钩子
    • [x] 完整文档

🔮 未来功能

  • [ ] 医生模式 - MCP健康检查和自动修复
  • [ ] 后台监控 - 守护进程自动模式同步
  • [ ] AI辅助 - 复杂问题诊断
  • [ ] 项目级别支持 - 支持项目级别的MCP
  • [ ] Web UI - 图形界面
  • [ ] 云备份 - 配置云同步

请参阅详细计划 user-requirements/docs/next-requirements.md

🤝 贡献

欢迎贡献！请查阅 开发者指南 了解如何参与开发。

贡献方法

  1. 分叉项目
  2. 创建功能分支（git checkout -b feature/amazing-feature）
  3. 提交更改（git commit -m 'feat: 添加神奇功能'）
  4. 推送到分支（git push origin feature/amazing-feature）
  5. 创建Pull Request

代码风格

  • 遵循PEP 8
  • 使用Black格式化
  • 使用Ruff检查
  • 完整类型标注
  • 编写测试

提交信息格式

遵循 常规提交：

feat: 新功能
fix: Bug修复
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试相关
chore: 构建工具

📄 许可证

MIT许可证 - 详情见 LICENSE 文件

🙏 致谢

📞 联系信息

🌟 Star历史

如果这个项目对你有帮助，请给我们一个Star ⭐️

版本：2.0.0 状态：✅ 所有核心功能完成（任务15/15） 最后更新：2025-10-28

来自Claude驱动开发 🤖