技术文档摘要

sync-mcp

一键式MCP配置同步工具。 中文

1. 概述

sync-mcp 是一个基于Node.js的命令行工具，旨在解决手动在多个IDE、代码编辑器和CLI工具之间同步通用MCP配置的痛点。用户可以使用简单的命令安全地将一个工具（源）的配置文件同步到另一个工具（目标），从而实现统一和自动化的配置管理。

2. 技术规格

• 环境：Node.js 18+（需要ESM支持和现代API）。
• 发布方式：通过npm发布，支持直接执行 npx sync-mcp 或全局安装 npm i -g sync-mcp。
• 运行依赖：仅依赖跨平台文件系统和CLI交互库；无需本地编译环境。
• 支持平台：稳定运行于Linux、Windows和macOS。

3. 使用方法

3.1. 直接同步

通过提供源和目标工具的关键字来直接执行同步。

npx -y sync-mcp <source_keyword> <target_keyword>

3.2. 交互式同步

当命令没有参数时，进入交互模式。

npx -y sync-mcp

操作流程：

1. 选择源：

   ? 选择配置源文件：(使用箭头键)  
   > 1. VS Code (~/.vscode/mcp.json)  
       2. Cursor (~/.cursor/mcp.json)  
       3. GitHub Copilot CLI (~/.copilot/mcp-config.json)  
       4. 自定义
   

2. 选择目标：

   ? 选择配置目标文件：(使用箭头键)  
   > 1. VS Code (~/.vscode/mcp.json)  
       2. Cursor (~/.cursor/mcp.json)  
       3. GitHub Copilot CLI (~/.copilot/mcp-config.json)  
       4. 自定义 (选择一个目标工具或创建新的配置)
   

4. 工具匹配关键字

工具名称	支持的关键字
Codex	codex, openai, codex cli
Claude Code	claude, claude-code, claude code, anthropic
Cursor	cursor, cursor ide
Gemini CLI	gemini, gemini cli, google, gcloud
GitHub Copilot CLI	copilot, copilot cli, github, gh
Visual Studio Code	vscode, vs code, vs-code, code

5. 支持的工具及其配置路径

工具名称	Linux/macOS 路径	Windows 路径	文档链接
Codex	~/.codex/config.toml	%USERPROFILE%\.codex\config.toml	Codex 配置
Claude Code	~/.claude.json	%USERPROFILE%\.claude.json	Claude Code MCP指南
Cursor	~/.cursor/mcp.json	%APPDATA%\Cursor\mcp.json	Cursor MCP指南
Gemini CLI (gcloud)	~/.gemini/settings.json	%APPDATA%\.gemini\settings.json	Gemini CLI MCP服务器
GitHub Copilot CLI	~/.copilot/mcp-config.json	%USERPROFILE%\.copilot\mcp-config.json	Copilot CLI MCP使用
Visual Studio Code	~/.vscode/mcp.json	%APPDATA%\Roaming\Code\User\mcp.json	VS Code MCP服务器

5.1. Codex

默认配置文件：~/.codex/config.toml

# ~/.codex/config.toml  
[mcp_servers.context7]  
command ="cmd"  
args = [  
    "/c", "npx", "-y",  
    "@upstash/context7-mcp",  
    "--api-key="YOUR_API_KEY",  
    "--stdio"  
]  
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }  
startup_timeout_ms = 60_000

5.2. Claude Code

默认配置文件：~/.claude.json

{  
  "mcpServers": {  
    "context7": {  
        "type": "stdio",  
        "command": "npx",  
        "args": [  
            "-y",  
            "@upstash/context7-mcp",  
            "--api-key",  
            "YOUR_API_KEY"  
        ],  
        "env": {}  
    }  
  }  
}

5.3. Cursor

默认配置文件：~/.cursor/mcp.json

{  
    "mcpServers": {  
        "context7": {  
            "command": "npx",  
            "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]  
        }  
    }  
}

5.4. Gemini CLI (gcloud)

默认配置文件：~/.gemini/settings.json

{  
    "mcpServers": {  
        "context7": {  
            "command": "npx",  
            "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]  
        }  
    }  
}

5.5. GitHub Copilot CLI

默认配置文件：~/.copilot/mcp-config.json

{  
  "mcpServers": {  
        "docs": {  
            "command": "npx",  
            "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]  
        }  
  }  
}

5.6. Visual Studio Code

默认配置文件：~/.vscode/mcp.json

{  
    "servers": {  
        "context7": {  
            "command": "npx",  
            "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]  
        }  
    }  
}

6. 核心功能

• 双模式操作：支持快速直接单行命令同步和引导式交互模式。
• 模糊参数匹配：用户不需要记住确切的工具名称；工具会自动匹配常见关键字。
• 跨平台兼容性：完美支持Linux、Windows和macOS环境，自动处理不同操作系统路径格式。
• 自动路径检测：内置主流开发工具的默认配置路径，自动发现本地存在的配置文件。
• 安全备份机制：在执行任何覆盖操作前，自动备份目标配置文件，确保操作可逆并防止意外数据丢失。
• 自定义与扩展：支持手动指定配置文件路径，并能自动创建不存在的目标文件。

7. 文件备份机制

安全性是此工具的核心原则之一。在任何同步操作（即覆盖目标文件）发生之前，必须执行以下备份过程：

1. 安全原则：在任何操作写入目标文件之前，必须完成备份以确保操作可逆。
2. 默认位置：在用户的主目录中创建一个 ~/.sync-mcp/backup/ 目录。如果不存在，则自动创建。
3. 备份内容：当前目标文件的完整副本。
4. 备份路径：
   • 根目录：~/.sync-mcp/backup/
   • 子目录结构：/<时间戳>/<原始目录结构>/<原始文件名>
   • <时间戳>：执行同步操作时的Unix时间戳（毫秒），例如 1677619200000
5. 示例：
   • 操作：npx sync-mcp vscode cursor
   • 时间：2025-10-24 18:00:00（假设时间戳为 1761319200000）
   • 目标文件：Linux上的 ~/.cursor/mcp.json
   • 动作：程序将 ~/.cursor/mcp.json 复制到 ~/.sync-mcp/backup/1761319200000/.cursor/mcp.json
   • 这样可以防止备份文件被覆盖，并保留原始文件的路径结构，便于查找和恢复。

8. 平台兼容性

• 操作系统：必须在主流Linux发行版（如Ubuntu、CentOS等）、Windows 10/11和macOS上稳定运行。
• 路径处理：内部逻辑必须使用Node.js path模块中的函数（如path.join()和path.resolve()）来处理文件路径。禁止硬编码/或\。