给 Claude Code 和 Cursor 配 MCP 终于不用手写 JSON 了：一个命令自动同步还省 Token
先说说我自己的情况。从 Claude Code 到 Cursor，MCP（Model Context Protocol）配置我前后折腾了大半个月，最直观的感受是：两边配置语法高度相似，但细节差异非常烦人。Claude Code 写在~/.claude.json里，Cursor 写在~/.cursor/mcp.json里，每次新加一个 MCP Server，我都要在两个文件里分别改一遍。手写 JSON 最怕的不是写错，是改完以后某个逗号或者引号没配对，工具直接罢工。后来我干脆写了一个本地同步脚本，一条命令完成配置分发，顺带把配置体积精简了不少。这段时间用下来的体验是：省心，也真的省 Token。
这篇内容不讲高大上的框架，就分享我给 Claude Code 和 Cursor 统一配置 MCP 的完整方案，包括配置文件的差异、为什么用 JSON 配置中心、怎么用一条命令完成同步、以及我在实操中踩过的坑。适合正在手动维护多份 MCP 配置的人，也适合刚接触 MCP 但不想被 JSON 折腾的朋友。
1. 项目整体设计思路：从“两处维护”变成“一处维护”
1.1 不要急着写代码，先看清痛点
最开始的痛点是频率问题。MCP 生态更新很快，今天装个文件读取服务，明天加个数据库查询服务，后天又想在 Cursor 里用一个只在 Claude Code 上验证过的工具。每新增一个服务，我都要先打开 Claude Code 的配置文件，再打开 Cursor 的配置文件，各自检查当前有没有写重复条目，然后决定是新增还是更新。时间长了，两份配置开始不一致：某次我在 Cursor 里把服务的端口改成了 9000，Claude Code 那边还停在 9001，结果两边行为完全不一样，排查了很久才发现是配置漂移。
第二个痛点是格式差异。Claude Code 和 Cursor 虽然都走 MCP 协议，但配置文件的结构不完全相同。Claude Code 的 JSON 结构偏重“进程启动参数”形容，每个 MCP Server 要写type、command、args、env这些键，装在不同的顶层作用域下；Cursor 则比较直白，就是一个mcpServers对象。我最初想写一个工具，把所有配置统一放进一个“中立格式”的源文件里，再按照目标工具的要求做转换——这个思路后来被证明是对的方向。
第三点才是真正的隐性成本：Token。一开始我没意识到，MCP 配置本身也是要进上下文的。当你和 Claude Code 对话时，工具列表和相关配置信息会被模型读取；如果配置文件里塞满注释、空格、重复条目，无形中就在占用宝贵的上下文窗口。尤其是 Cursor，在启动时会加载并解析配置，配置越乱，潜在的错误和无效内容越多。把配置精简成“只保留必要字段”，其实也是在帮模型减负。
1.2 为什么不用图形化工具，而是本地脚本
市面上有不少 GUI 形式的 MCP 配置管理器，我也试用过。坦白说，界面友好不等于效率高。每次配置都要打开面板、填写多个输入框、点保存，再切到另一个工具导入，操作路径并不短。而且大部分 GUI 工具并没有解决“两份配置之间的一致性问题”，它们只是把 JSON 编辑过程图形化了。
我需要的工具必须满足三个基本要求：离线可用、可脚本化、可复制。说白了，我可以把配置文件提交到自己的代码仓库里，换机器、换环境，一条命令就能恢复全部 MCP 配置。这个需求用一个本地 Python 脚本就满足了，不依赖网络服务，也没有隐私问题。MCP 配置里经常会写数据库连接串、内部 API 密钥，这些信息我不想经过任何第三方工具。
1.3 方案选型：标准配置源 + 双目标生成
最后定的思路很简单：一个mcp.sources.json作为唯一事实来源，一个mcp-sync.py脚本负责读取源文件，然后生成 Claude Code 和 Cursor 各自的配置。
mcp.sources.json（统一维护，只写服务名、命令、参数、环境变量） | | mcp-sync.py v ~/.claude.json（自动更新 Claude Code 需要的结构） ~/.cursor/mcp.json（自动更新 Cursor 需要的结构）为什么要“中立格式”？因为我不想在写源文件时脑子里还要去想目标工具的细节。源文件只描述“这个 MCP 服务叫什么、怎么启动、需要哪些参数”，生成部分完全交给脚本。这样做还有一个好处，未来如果第三个编辑器也支持 MCP，我只需要在脚本里增加一个输出函数，源文件不需要任何改动。
2. 核心原理与配置细节：MCP 配的到底是什么
很多朋友第一次配 MCP，习惯直接复制文档里的 JSON 片段，一粘贴就完事了。但一旦你想自动化管理，就必须理解这些 JSON 背后的含义。
2.1 MCP Server 的启动方式：command + args + env
MCP 的本质是让 AI 编程工具能够通过标准化的接口调用外部工具。在本地配置一个 MCP Server，核心其实是配置“工具如何启动这个服务进程”。绝大多数本地 MCP Server 都可以用三条信息描述：
command：启动命令，通常是npx、uvx、node、python或某个可执行文件的绝对路径。args：传给命令的参数，比如-y 某个包名，或者某个脚本路径、--port 9000。env：环境变量，比如 API Key、数据库地址、模型服务地址等。
几乎不会有第四种情况。掌握了这个通用描述，你就掌握了所有本地 MCP Server 的配置核心。其他字段，比如type、disabled、title，都属于辅助信息，不是启动所必需的。
2.2 两个工具配置文件的差异对比
先拿最简单的例子来说：我想注册一个叫my-knowledge-base的本地知识库服务，它通过node /path/to/server.js启动，需要环境变量KB_TOKEN=abc123。
在 Cursor 的~/.cursor/mcp.json里，配置长这样：
{ "mcpServers": { "my-knowledge-base": { "command": "node", "args": ["/path/to/server.js"], "env": { "KB_TOKEN": "abc123" } } } }在 Claude Code 的~/.claude.json里，结构就明显不一样了。Claude Code 在较新的配置格式中把 MCP 服务放在某个 project 作用域下，默认是mcpServers，每个服务同样有command、args，但有时候还要加type: "stdio"或"sse"，而且整个文件被层层嵌套包裹：
{ "projects": { "/path/to/my/project": { "mcpServers": { "my-knowledge-base": { "type": "stdio", "command": "node", "args": ["/path/to/server.js"], "env": { "KB_TOKEN": "abc123" } } } } } }注意这里的关键：Claude Code 的配置是按项目作用域划分的，而 Cursor 是全局一份配置。这个差异导致你不能简单地把同一个 JSON 文件复制过去用，必须做结构转换。手动做一次转换还好，做十次就容易出错。
2.3 为什么“省 Token”和配置结构有关系
这是我之前完全没想到的一点，后来在一次实际对话中发现了端倪。当模型工具被 MCP 加载时，服务描述信息、工具定义、配置摘要都会被模型读取。如果配置对象特别大，里面还塞了一堆注释圆括号、不必要的空行、重复的默认值，那这些内容会占据上下文开销。
举一个直观的例子。一个配置源文件里写了 30 个 MCP 服务，每个服务的配置因为历史原因保留了不同的写法和大量注释，那么模型每次初始化工具列表时读取的内容体积会显著增加。而用一个自动化脚本统一生成配置，生成时会过滤掉空值字段，固定键名顺序，输出稳定的紧凑结构。这样不仅能避免部分工具在使用时的信息冗余，还能降低因格式不一致导致的解析错误概率。
当然，省 Token 不能只靠配置文件瘦身，还需要配合“按需启用”的习惯。如果你 30 个服务里只有 5 个常用，其余都是实验性质，最好通过脚本参数控制哪些服务可以同步。我的脚本里加了一个enabled字段，值为true的才写入目标配置，这样每个工具加载的条目数都控制在合理范围。
3. 实操过程：写一个可以放心使用的同步脚本
3.1 准备工作：确定源文件目录
我建议所有 MCP 配置统一放在一个独立目录里，比如~/mcp-config/。这样做的好处是备份、迁移都方便。我个人的目录结构是这样的：
~/mcp-config/ ├── mcp.sources.json ├── mcp-sync.py └── output/mcp.sources.json是源文件，mcp-sync.py是同步脚本，output/存放生成的目标配置备份，方便对比。你也可以直接把生成结果写到工具默认的路径，但在初期建议先输出到一个临时目录，人工确认无误后再启用覆盖写功能。
3.2 编写标准源文件
这是整个项目最核心的一步。源文件的格式要尽量中立，字段命名要清晰。以我使用的格式为例：
{ "servers": [ { "name": "docs-reader", "command": "npx", "args": ["-y", "mcp-docs-reader"], "env": { "DOCS_TOKEN": "xxx" }, "enabled": true, "description": "读取本地文档目录并生成摘要" }, { "name": "database-query", "command": "node", "args": ["/home/user/services/db-mcp/server.js"], "env": { "DB_URL": "postgresql://localhost/mydb" }, "enabled": true }, { "name": "experimental-service", "command": "python", "args": ["-m", "my_experimental"], "env": {}, "enabled": false } ] }字段说明：
name：MCP 服务的唯一标识，两个工具里都会显示这个名字。command和args：启动服务的完整命令。env：环境变量，没有就留空对象。enabled：决定是否同步到目标工具，这样你可以保留不常用的服务，但不让它占用每次加载的配置体积。description：可有可无，面向维护者自己阅读，不会被同步到目标配置里。
关键点来了：我只把“必要字段”放入目标配置，description这种面向人的信息不会出现在最终 JSON 里。这样既保证了可维护性，又让目标配置保持精简。另外，我会统一 JSON 键的书写顺序，比如 Cursor 配置里固定是command、args、env的顺序。固定顺序有几个好处：生成的配置文件 diff 看起来干净，重复运行脚本结果稳定，也减少了源码包体积。
3.3 第一个版本的同步脚本：核心逻辑拆解
脚本本身不用写得很复杂，核心流程就三步：读取源文件、过滤有效服务、根据不同目标生成配置。我先把最核心的 Python 脚本思路展示出来：
import json import os from collections import OrderedDict SOURCE_PATH = os.path.expanduser("~/mcp-config/mcp.sources.json") def load_sources(path): with open(path, "r", encoding="utf-8") as f: data = json.load(f) return data.get("servers", []) def filter_enabled(servers): return [s for s in servers if s.get("enabled", True)] def to_standard_server(server): out = OrderedDict() out["command"] = server["command"] out["args"] = server.get("args", []) # 只有 env 非空时才写入，避免多余的空对象 if server.get("env"): out["env"] = OrderedDict(sorted(server["env"].items())) return out def generate_cursor_config(servers): mcp_servers = OrderedDict() for s in servers: mcp_servers[s["name"]] = to_standard_server(s) return OrderedDict([ ("mcpServers", mcp_servers) ]) def generate_claude_config(servers, project_path="/path/to/my/project"): mcp_servers = OrderedDict() for s in servers: mcp_servers[s["name"]] = to_standard_server(s) return OrderedDict([ ("projects", OrderedDict([ (project_path, OrderedDict([ ("mcpServers", mcp_servers) ])) ])) ]) def is_same_config(new, old_path): try: with open(old_path, "r", encoding="utf-8") as f: old_data = json.load(f) except FileNotFoundError: return False return json.dumps(new, ensure_ascii=False) == json.dumps(old_data, ensure_ascii=False) def write_json(path, data): tmp_path = path + ".tmp" with open(tmp_path, "w", encoding="utf-8") as f: json.dump(data, f, indent=2, ensure_ascii=False) os.replace(tmp_path, path) def main(): servers = load_sources(SOURCE_PATH) enabled_servers = filter_enabled(servers) cursor_config = generate_cursor_config(enabled_servers) cursor_path = os.path.expanduser("~/.cursor/mcp.json") if not is_same_config(cursor_config, cursor_path): write_json(cursor_path, cursor_config) print(" cursor 配置已更新") else: print(" cursor 配置无变化") claude_config = generate_claude_config(enabled_servers) claude_path = os.path.expanduser("~/.claude.json") if not is_same_config(claude_config, claude_path): write_json(claude_path, claude_config) print(" claude 配置已更新") else: print(" claude 配置无变化") if __name__ == "__main__": main()几个设计细节值得展开说一下。
我用了OrderedDict来保证键的顺序固定，这一点在生成稳定配置时非常有用。很多工具在对比配置是否变化时，会直接比较 JSON 字符串，如果键顺序不稳定，即使内容没变也会判定为“有变化”，导致每次运行刷新文件，进而引发不必要的重载。
我再加了is_same_config函数来做配置对比。如果目标文件已经和将要生成的内容完全一致，就直接跳过写入。这个优化在做持续集成时特别重要——你不想每次跑脚本都改动工具的配置文件，因为很多工具会监听配置文件变化并重启服务。
os.replace是事务性写入的关键。直接open(path, "w")写入如果中途报错，可能会留下一个残缺的 JSON 文件，工具加载时会直接失败。用os.replace先把内容写到临时文件，再原子性地替换，这个细节能避免很多偶发问题。
3.4 一条命令自动同步的完整流程
配置好了以后，使用方式非常简单：
cd ~/mcp-config python3 mcp-sync.py执行后，屏幕上会输出类似这样的结果：
读取配置源: /root/mcp-config/mcp.sources.json 发现 10 个服务，其中启用 8 个 cursor 配置已更新 claude 配置无变化如果你用了 Cursor，可能需要让 Cursor 的 MCP 面板重新加载一下，或者在设置里点一下刷新按钮。Claude Code 一般来说重启一次会话或者执行一次/mcp命令就能看到最新列表。整个过程几十秒，你不再需要手动打开两个路径，复制粘贴，检查逗号和冒号。
3.5 进阶：按项目作用域给 Claude Code 配置
前面提到，Claude Code 的配置是按项目作用域区分的。如果你的实际情况是不同项目需要不同的 MCP 服务，那么源文件可以进一步扩展成支持分组：
{ "servers": [ { "name": "db-query", "command": "node", "args": ["/opt/db/server.js"], "enabled": true, "project": "project-alpha" } ] }脚本在生成 Claude Code 配置时，根据project字段把服务分到不同的作用域下。这个扩展不难，核心就是把原来单个mcpServers的生成逻辑改成分组逻辑。多维护一层映射关系而已。
3.6 其他工具的扩展思路
如果你用的不只有 Claude Code 和 Cursor，还有一个我偶尔会碰到的本地工具也支持自定义 MCP 配置，那怎么办？扩展逻辑是一样的。找到那个工具读取配置的路径和 JSON 结构，在脚本里加一个generate_xxx_config函数，然后在main里调用就行。核心代码是通用的：标准服务对象 → 目标格式对象。
也就是说，整个工具的真正价值不在于能管两个工具，而在于建立了一套“一次定义、多处生成”的配置流。MCP 的配置格式虽然各个工具略有差异，但根源都离不开command、args、env这三个键。抓住这个底层共识，其他都是映射层的工作。
4. 常见问题与排查技巧实录
这个部分我全是在实际操作中碰到的真实问题，不一定每个都会发生在你身上，但一旦发生，下面这些排查思路能帮你节省不少时间。
4.1 同步后工具看不到 MCP 服务
先说最让人沮丧的场景：脚本运行显示“配置已更新”，但打开工具一看，MCP 列表空空如也。排查顺序如下：
先检查目标配置路径是否正确。Cursor 在 macOS 上的配置路径是~/.cursor/mcp.json，在 Windows 上可能是%USERPROFILE%\.cursor\mcp.json。如果你的 Cursor 版本比较老或者用了自定义配置目录，路径可能不一样。Claude Code 同理，某些版本可能把配置放在~/Library/Application Support/Claude/下面。路径写错是最常见的原因。
再检查配置文件的 JSON 是否合法。虽然脚本已经做了格式化处理，但你原来可能手动改过部分内容，导致 JSON 中出现标准解析器能跳过、但工具自己的解析器无法处理的内容。最简单的排查方法：用 Python 重新解析一遍生成的文件，确认没问题。
最后看服务状态。很多 MCP Server 是懒加载的，工具并不会在启动时一次性全部启动，而是当你用到某个工具时才开始拉起对应进程。如果某个服务的command写错了，工具不一定报错，它只是静默失败。这时你需要手动在终端跑一下命令，确认这个服务能不能正常启动。
4.2 同步脚本反复显示“配置已更新”
这个问题的根源就是前面提到的键顺序不固定。如果脚本每次运行，生成的 JSON 字符串都因为键顺序变化而不同，is_same_config就会一直判定为“有变化”，导致每次都重写文件。解决方式有两个：一个是使用OrderedDict固定顺序；另一个是在比较时对 JSON 做浅层排序后再比较。
我建议直接用固定顺序的方式，因为这样不但解决了“无变化却重写”的问题，还让配置文件更具可读性。比如环境变量里的键，我在生成时做了排序，这样每次运行结果完全一致。
4.3 环境变量丢失或者不生效
很多 MCP 服务需要读取环境变量才能运行。最常见的问题是：工具本身的环境变量和 MCP 配置里的env字段之间的继承关系不够直观。
在 Cursor 里，配置文件的env字段是在 MCP Server 进程启动时注入的。如果工具的 GUI 设置里设置了同名环境变量，可能会覆盖配置文件里的值，或者反过来。我建议在源文件里明确列出所有依赖的环境变量，不要依赖系统的全局变量。另一个容易忽略的点是，env里的值必须是字符串类型。如果你从某个配置里复制了数字或者布尔值，比如"port": 9000，工具的严格解析可能会报错。统一转成字符串会更保险。
4.4 Token 省不下来的原因分析
配置已经精简了，但 Token 开销还是很大，这种情况往往不是配置的问题，而是使用方式的问题。如果你在同一个会话里加载了非常多的 MCP 工具，模型的上下文消耗自然会涨。我的经验是：把不常用的服务enabled设为false，需要时再改回true并执行一次同步命令。这比每次手工删除配置要安全得多。
还有一个容易忽略的细节：某些 MCP 服务会向模型注入工具描述，描述越长，单次工具调用的开销越大。如果你发现自己常用的某个服务特别费 Token，可以去留意服务本身输出的工具定义是否过于冗长。这个属于 MCP Server 开发层面的话题了，但作为使用者，你可以通过比对不同服务的工具定义长度来判断要不要换一个更轻量的替代方案。
4.5 多条命令跨环境同步问题
一台开发机、一台办公机，配置总是不同步，怎么办？我的做法是把~/mcp-config/作为一个私有仓库来管理，换了机器以后直接拉取代码，运行python3 mcp-sync.py --force即可。--force参数可以在服务名相同但内容不同时，强制用源文件内容覆盖目标配置。为了避免误操作，我没有把--force做成默认行为，而是单独加的布尔参数，只有在明确需要覆盖时才用。
5. 一些后续可以继续优化的方向
这个项目目前已经满足了我的日常使用，但回头来看，还有几个方向值得继续加东西。
一个是配置校验。现在的脚本只做格式层面的 JSON 解析，没有校验command是否存在、args是否是数组、env是否是对象。后续可以加一个validate_sources函数，在生成前做一次结构检查，把问题直接在源头拦截掉。
另一个是服务健康检查。脚本如果能在生成配置后自动尝试启动每个 MCP Server，并输出“启动成功”“启动失败”的提示，那就可以提前发现配置错误，不用等到工具里实际用到才发现。不过这个功能要注意设计：有些服务依赖图形界面或者交互输入，启动后会一直挂在前台，不能用简单粗暴的“等待超时”来判断。
再一个是自动备份。每次覆盖写入前，把当前旧配置复制一份到output/history/目录里，以时间戳命名。这样如果某次同步的结果不满意，可以快速回滚。做这个只需要在write_json里加几行代码，但日常维护的安心感会明显提升。
6. 写在最后的一点使用心得
这套方案我用到现在，最大的感受不是“省了多少配置步骤”，而是“终于不用在每次新增服务时都产生恐惧感了”。以前每改一次 JSON，都要在心里默念三遍“别写错逗号”；现在改源文件、跑命令、起服务，三步走完，剩下的交给脚本处理。
如果你只是有一两个 MCP 服务要配，用不用这套方案影响不大，手写 JSON 也花不了两分钟。但当你慢慢引入了数据库工具、文档辅助工具、代码检索服务，配置列表开始超过十个的时候，你会发现人工维护两份配置的代价越来越大。到那个阶段再回头来做自动化，成本反而更高。不如趁着现在配置还少，把源文件建起来，哪怕先只管理一个服务，后面每加一个服务都只是往列表里加一行的事。
最后给一个小建议：源文件里每个服务的name字段，尽量用稳定且容易识别的英文名。不要今天叫db-query，明天改成query-db-v2，因为两个工具的本地配置缓存可能会记住旧名字，改完以后需要重启工具才生效。稳定的命名能让你的配置管理少很多不必要的折腾。
