内容
<div align="center">
# 🔄 mcp-sync
### 一个配置搞定所有（Claude Code、Cursor 和 VS Code）
[](./LICENSE)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
[](https://github.com/sbotargues/mcpctl/pulls)
**不再手动编辑三个不同的 JSON 文件来安装一个 MCP 服务器 😭**
</div>
---
## 🤔 问题
MCP 服务器为 AI 编程工具提供了超能力 — 读取文件、访问数据库、搜索网络。很酷。但是，每个工具都希望以其**自己的**略有不同的 JSON 方言来了解它们：
| | 期望其配置在... |
| -------------- | ------------------------- |
| 🟠 Claude Code | `.mcp.json` |
| ▲ Cursor | `.cursor/mcp.json` |
| 🔵 VS Code | `.vscode/mcp.json` |
所以，你要么提交这些文件（👋 你好，git 历史记录中的泄露令牌），要么整个团队手动保持三个几乎相同的 JSON 文件同步，永远为每个新服务器手动同步。 不。
## ✨ 解决方案
你写**一个**列表。`mcp-sync` 会处理好其他事情。
```sh
mcp-sync sync
```
```
? 选择要配置的工具
❯◉ Claude Code
◯ Cursor
◯ VS Code
? 选择要配置的 MCP 服务器
❯◉ 文件系统 - 在允许的本地目录中读取和写入文件
◉ 内存 - 跨会话的持久知识图谱内存
◯ GitHub - 搜索和管理 GitHub 仓库、问题和拉取请求
...
✔ 为 Claude Code 同步了 2 个 MCP 服务器。
```
就这样。选择你的工具，选择你的服务器，完成。稍后重新运行，它只会触及更改的内容 — 你手动添加的任何内容都会保留。
> [!TIP]
> 需要个人 API 令牌的服务器（`github`、`slack`、`brave-search`）**默认不选中**。没有人被迫去查找令牌，只是为了试用该功能。
## 🚀 快速开始（不需要阅读其他内容，我们保证）
**1. 获取代码**
<table>
<tr><td>
**npm**
```sh
git clone https://github.com/sbotargues/mcpctl.git
cd mcpctl
npm install
npm run build
```
</td><td>
**yarn**
```sh
git clone https://github.com/sbotargues/mcpctl.git
cd mcpctl
yarn install
yarn build
```
</td></tr>
</table>
**2. 运行它**
```sh
node dist/cli.js sync
```
想直接输入 `mcp-sync`？在构建后运行 `npm link`（或 `yarn link`）一次 — 它会从你的克隆中全局链接。然后：
```sh
mcp-sync sync
```
**3. 回答屏幕上的问题** — 空格选择，回车确认。粘贴令牌（如果需要，输入时隐藏）。
**4. 重启你的 AI 工具。** 你的服务器出现了。 🎉
在任何时候运行 `sync` 以添加或删除服务器。
### 🧩 想要自己的服务器而不是示例？
在任何文本编辑器中打开 `.mcp-sync.json`。删除你不需要的内容，复制一个条目并更改名称/命令为你自己的。**无需编写代码** — 参见下面的 [清单格式](#-the-manifest-mcp-syncjson)。
## 📖 命令
| 命令 | 它执行的操作 |
| ----------------- | -------------------------------------------------------------------- |
| `mcp-sync init` | 创建一个包含几个众所周知的 MCP 服务器的启动器 `.mcp-sync.json` |
| `mcp-sync list` | 列出 `.mcp-sync.json` 中定义的服务器 |
| `mcp-sync sync` | 交互式：选择工具 → 选择服务器 → 生成个人配置 |
*（将 `mcp-sync` 替换为 `node dist/cli.js`，如果你没有链接它 — 参见 [快速开始](#-quick-start-no-need-to-read-the-rest-we-promise)）*
`sync` 支持 `--dry-run` 以预览而不写入任何内容。
## ⚙️ `sync` 的工作原理
1. **选择你的工具** — Claude Code、Cursor、VS Code，任意组合。
2. **选择你的服务器** — 默认启用 `defaultEnabled`，除非你已经有一个配置，在这种情况下，它会反映已经存在的内容。
3. **仅需缺失的机密** — 只需一次输入，之后将重复使用。
4. **合并，永不删除** — 您手动添加的任何内容都不会被删除。如果取消选择某个服务器，则只会删除该条目。
> [!NOTE]
> 所有三个生成的配置文件（`.mcp.json`、`.cursor/mcp.json`、`.vscode/mcp.json`）都应被 **gitignore**。它们是个人文件。
## 🔒 我的令牌去哪了？
不会去你不想去的地方。具体来说：
- 清单（`.mcp-sync.json`）只存储服务器需要的环境变量的名称（例如 `GITHUB_PERSONAL_ACCESS_TOKEN`），而非真实值。这就是提交它的全部意义。
- 如果缺少令牌，则直接在您的终端中输入，输入时隐藏 — 不会被发送、记录或在屏幕上显示。
- 它只写入您的本地、被 gitignore 的 `.mcp.json` / `.cursor/mcp.json`。它从不涉及 GitHub、npm 或该项目的代码。
- 特别是对于 VS Code，它甚至不会以纯文本形式写入 — VS Code 会提示输入它并将其存储在其自己的安全存储中。
## 🗂 清单：`.mcp-sync.json`
```jsonc
{
"servers": [
{
"name": "github",
"description": "搜索和管理 GitHub 仓库、问题和拉取请求",
"defaultEnabled": false,
"secrets": [
{ "env": "GITHUB_PERSONAL_ACCESS_TOKEN", "description": "GitHub 个人访问令牌" }
],
"targets": {
"claude": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
"cursor": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
"vscode": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
}
}
]
}
```
- `defaultEnabled: false` → 用于需要个人机密的服务器。选择加入，而不是选择退出。
- `targets` 是一个 **映射**，不是固定字段 — 稍后添加第四个工具不需要模式更改。
- 服务器上没有 `vscode` 目标？它就不会被写入 `.vscode/mcp.json`。很简单。
该存储库自我测试 — [`.mcp-sync.json`](./.mcp-sync.json) 是一个真实的示例。
## 🙅 为什么不直接提交配置文件？
因为机密最终会出现在其中，并且因为三个工具需要三个不同的形状来表示相同的想法。`mcp-sync` 保留了一个真实的来源，并为每个工具、每个人适配 — 这样再也不会有人手动复制粘贴 JSON 了。
---
<div align="center">
因为编辑同一个 JSON 三次感觉像是一个性格缺陷
⭐ 如果它让你摆脱了 JSON 地狱，请给它点赞 · [问题和 PR 欢迎](https://github.com/sbotargues/mcpctl/issues)
**MIT 许可**
</div>
