MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

S
Syncmcp
by @richblack
GitHub Repo(4 stars)

MCP server by richblack

Created 10/24/2025
Updated about 2 months ago
README
View Source
Repository documentation and setup instructions

SyncMCP - MCP 配置同步工具 🚀

Version Python License

智能化的 MCP (Model Context Protocol) 配置同步工具，讓您輕鬆管理多個 AI 客戶端的配置。

🤖 100% 由 Claude 開發，持續進化中

✨ 特色

  • 🔄 智能同步 - 自動選擇最新配置，一鍵同步所有客戶端
  • 💾 自動備份 - 每次同步前自動備份，安全無憂
  • 🎨 互動介面 - 友善的 Terminal UI，非技術用戶也能輕鬆使用
  • 🤖 MCP Server - 作為 MCP Server，讓 Claude 幫您管理配置
  • 🌍 全局命令 - 安裝後可在任何位置執行
  • 🔍 差異偵測 - 智能分析配置差異，提供清晰報告
  • 🛡️ 錯誤回滾 - 同步失敗時自動恢復備份

📖 目錄

問題與解決方案

問題

每個 AI Agent（Claude Desktop、Claude Code、Roo Code、Gemini CLI）都有各自的 MCP Server 配置文件。當您在一個客戶端安裝或修改 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 .

5 分鐘入門

# 1. 檢查系統是否正常
syncmcp doctor

# 2. 查看當前配置狀態
syncmcp status

# 3. 預覽同步（不實際修改）
syncmcp sync --dry-run

# 4. 執行同步
syncmcp sync

# 5. (可選) 使用互動模式
syncmcp interactive

支援的客戶端

客戶端特性對比

| 特性 | Claude Code | Roo Code | Claude Desktop | Gemini CLI | |------|------------|----------|----------------|------------| | 配置層級 | | | | | | 全域配置 | ✅ | ✅ | ✅ | ✅ | | 專案級配置 | ✅ | ✅ | ❌ | ❌ | | 傳輸類型 | | | | | | stdio (本地) | ✅ | ✅ | ✅ | ✅ | | sse (遠端) | ✅ | ⚠️ 未測試 | ❌ | ⚠️ 未測試 | | http (遠端) | ✅ | ⚠️ 需轉為 streamable-http | ❌ | ⚠️ 未測試 | | 特殊類型 | | | | | | streamable-http | ❌ | ✅ Roo 專有 | ❌ | ❌ |

類型轉換規則

SyncMCP 會自動處理不同客戶端的格式差異：

| 同步方向 | 轉換規則 | 說明 | |---------|---------|------| | Roo Code → Claude Code | streamable-http → sse 或 http | 根據是否有 headers 決定 | | Claude Code → Roo Code | sse/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)

友善的 Terminal 選單介面。

syncmcp interactive

功能:

  • 🔄 互動式同步 - 預覽變更 → 確認 → 執行
  • 📊 配置狀態 - 表格顯示所有客戶端
  • 🔍 差異分析 - 顏色標示變更
  • 📜 同步歷史 - 查看過往記錄
  • ⏮️ 恢復備份 - 從歷史備份恢復

操作方式:

  • ↑/↓ 選擇選項
  • Enter 確認
  • Ctrl+C 退出

6. MCP Server 整合

讓 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] Rich 彩色輸出
    • [x] 系統診斷工具

  • [x] 開發者工具

    • [x] MCP Server 整合（4 個工具）
    • [x] 完整測試套件（92 個測試）
    • [x] CI/CD Pipeline
    • [x] Pre-commit Hooks
    • [x] 完整文檔

🔮 未來功能

  • [ ] Doctor Mode - MCP 健康檢查與自動修復
  • [ ] 背景監控 - Daemon 模式自動同步
  • [ ] AI 協助 - 複雜問題診斷
  • [ ] 專案級別支援 - 支援專案級別 MCP
  • [ ] Web UI - 圖形化介面
  • [ ] 雲端備份 - 配置雲端同步

詳細規劃請查看 user-requirements/docs/next-requirements.md

🤝 貢獻

歡迎貢獻！請查看 開發者指南 了解如何參與開發。

貢獻方式

  1. Fork 專案
  2. 建立功能分支 (git checkout -b feature/amazing-feature)
  3. 提交變更 (git commit -m 'feat: add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 建立 Pull Request

程式碼風格

  • 遵循 PEP 8
  • 使用 Black 格式化
  • 使用 Ruff 檢查
  • 完整的型別標註
  • 撰寫測試

Commit 訊息格式

遵循 Conventional Commits:

feat: 新功能
fix: Bug 修復
docs: 文檔更新
style: 程式碼格式
refactor: 重構
test: 測試相關
chore: 建置工具

📄 License

MIT License - 詳見 LICENSE 文件

🙏 致謝

📞 聯絡方式

🌟 Star History

如果這個專案對您有幫助，請給我們一個 Star ⭐️

版本: 2.0.0 狀態: ✅ 所有核心功能完成（15/15 任務） 最後更新: 2025-10-28

由 Claude 驅動開發 🤖

Quick Setup
Installation guide for this server

Install Package (if required)

uvx syncmcp

Cursor configuration (mcp.json)

{ "mcpServers": { "richblack-syncmcp": { "command": "uvx", "args": [ "syncmcp" ] } } }