给 Claude Code 和 Cursor 配 MCP 终于不用手写 JSON 了一个命令自动同步还省 Token先说说我自己的情况。从 Claude Code 到 CursorMCPModel 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 里把服务的端口改成了 9000Claude 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 envMCP 的本质是让 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_TOKENabc123。在 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 } ] }字段说明nameMCP 服务的唯一标识两个工具里都会显示这个名字。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, encodingutf-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, encodingutf-8) as f: old_data json.load(f) except FileNotFoundError: return False return json.dumps(new, ensure_asciiFalse) json.dumps(old_data, ensure_asciiFalse) def write_json(path, data): tmp_path path .tmp with open(tmp_path, w, encodingutf-8) as f: json.dump(data, f, indent2, ensure_asciiFalse) 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因为两个工具的本地配置缓存可能会记住旧名字改完以后需要重启工具才生效。稳定的命名能让你的配置管理少很多不必要的折腾。