★ FEATURED ARTICLE 1. 手动维护 MCP 配置这件事到底卡在哪里如果你同时用 Claude Code 和 Cursor并且已经开始接 MCPModel Context Protocol服务大概率经历过这样一个阶段一开始兴致勃勃地配了两三个 server觉得挺新鲜过了一周server 数量涨到七八个每个工具各自维护一份 JSON改一个路径要同步改三四个文件改漏一个就出现这个工具里能用、那个工具里报错的诡异现象。MCP 的本质是给模型挂载外部能力——文件系统、数据库、浏览器、第三方 API 等等。Claude Code 读的是它自己的一套配置文件Cursor 读的是~/.cursor/mcp.json或者项目级.cursor/mcp.json两者字段结构相似但不完全一致路径写法、环境变量注入方式、启动命令的参数顺序都有细微差别。手动维护的痛点集中在三个地方重复劳动同一个 server 定义要在多个客户端各写一遍字段名还得按各家规范微调。Token 浪费很多人没意识到MCP server 的description、tools列表、参数 schema 会作为上下文注入到每次对话里。配置写得啰嗦等于每轮对话都在烧 Token。同步漂移今天在 Cursor 里加了个 server明天忘了往 Claude Code 里补两边能力不一致排查问题时容易怀疑人生。这篇要讲的就是用一个命令把这件事自动化一份源配置自动生成各客户端需要的 JSON顺带做 Token 瘦身。核心关键词就是 Claude Code、Cursor、MCP、JSON、Token 这五个下面会围绕它们把整套方案拆开讲透。适合谁看已经在用或准备用 Claude Code / Cursor 的开发者手上有多个 MCP server 需要统一管理的人对 Token 用量敏感、想让上下文更干净的人。不需要你懂 MCP 协议底层但至少要能看懂 JSON 和命令行。2. 先搞清楚 MCP 配置在两端到底长什么样在动手写同步脚本之前必须先把两边的配置结构摸清楚。很多人一上来就抄别人的 JSON结果字段对不上报错信息又含糊白白浪费时间。这一节把 Claude Code 和 Cursor 的 MCP 配置格式摊开对比。2.1 Claude Code 的 MCP 配置结构Claude Code 的 MCP 配置通常放在用户级配置目录下通过claude mcp add命令或者直接编辑配置文件来管理。它的核心结构是一个mcpServers对象每个 key 是 server 名字value 描述启动方式{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/me/projects], env: {} }, postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: postgresql://localhost:5432/mydb } } } }关键字段就三个command可执行程序、args参数数组、env环境变量。Claude Code 对args的顺序敏感尤其是npx -y后面紧跟包名这种写法顺序错了会直接启动失败。2.2 Cursor 的 MCP 配置结构Cursor 的 MCP 配置放在~/.cursor/mcp.json全局或项目根目录.cursor/mcp.json项目级。结构几乎一样但有两个差异点需要注意{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/me/projects] }, postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: postgresql://localhost:5432/mydb } } } }差异一Cursor 对空的env字段容忍度更高但某些版本对env为null会报错建议要么不写要么写{}。差异二Cursor 支持disabled字段来临时关闭某个 serverClaude Code 早期版本不支持需要靠注释或直接删除。2.3 两端字段对照表字段Claude CodeCursor备注顶层容器mcpServersmcpServers一致启动命令commandcommand一致参数数组argsargs一致顺序敏感环境变量envenvCursor 对 null 敏感禁用开关部分版本无disabled需按版本处理配置路径用户配置目录~/.cursor/mcp.json路径不同提示不同版本的 Claude Code 和 Cursor 对字段的支持会有出入动手前先用claude mcp list或 Cursor 的 MCP 面板确认当前版本行为别照搬网上过时的 JSON。理解了这张表同步脚本的设计思路就清晰了维护一份源配置用脚本按各端规则渲染出目标 JSON。源配置只写一次字段用统一命名渲染时再做映射。3. 设计一份源配置让同步有据可依同步方案的核心不是脚本本身而是那份源配置的设计。源配置设计得好脚本就是几十行的事设计得烂后面全是补丁。这一节讲怎么设计一份既能覆盖两端、又方便扩展的源配置。3.1 为什么不用某一端的配置当源最省事的做法是拿 Cursor 的mcp.json当源直接复制给 Claude Code。但这样做的隐患是一旦 Cursor 引入新字段比如disabled源配置就被污染了同步到 Claude Code 时可能触发未知字段报错。反过来也一样。正确做法是抽一层中间格式只保留两端都需要的公共字段再针对各端做差异化渲染。中间格式可以就是一个普通的 JSON 文件放在项目根目录比如mcp.source.json{ servers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ${PROJECT_ROOT}], env: {}, targets: [claude, cursor], description: 本地文件读写 }, postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: ${DATABASE_URL} }, targets: [claude, cursor], description: Postgres 查询 } } }这里引入了几个设计点targets字段声明这个 server 要同步到哪些客户端。有些 server 只在 Cursor 里用就没必要塞进 Claude Code减少上下文污染。${VAR}占位符路径和环境变量用占位符渲染时替换成实际值。这样源配置可以进版本库敏感信息走环境变量。description字段给人看的渲染时可以决定是否注入到目标配置有些客户端会把 description 当上下文能省则省。3.2 占位符替换的边界占位符替换看起来简单但有几个坑替换时机必须在渲染阶段替换不能提前替换后写回源文件否则源文件就被污染了。未定义变量遇到${DATABASE_URL}但环境变量没设应该报错退出而不是渲染成空字符串——空字符串会导致 server 启动后连不上库排查起来更费劲。转义如果某个参数里真的需要${字面量得约定一个转义写法比如$${。function resolvePlaceholders(value, env) { return value.replace(/\$\{(\w)\}/g, (_, name) { if (!(name in env)) { throw new Error(Missing env var: ${name}); } return env[name]; }); }这段逻辑虽短但未定义就报错这一条能帮你省下大量排查时间。3.3 源配置的版本管理策略源配置进 Git目标配置不进 Git。原因很简单目标配置里可能包含渲染后的绝对路径和敏感值而且它是生成物提交上去只会造成冲突。建议在.gitignore里加上.cursor/mcp.json .claude/mcp.json源配置mcp.source.json则正常提交。团队协作时每个人拉下代码跑一次同步命令就能得到符合自己环境的配置。4. 一个命令搞定同步脚本实现与 Token 瘦身前面铺垫了配置结构这一节进入正题写一个同步脚本一条命令把源配置渲染到两端同时做 Token 优化。脚本用 Node.js 写因为 Claude Code 和 Cursor 生态里 Node 最通用不需要额外装运行时。4.1 脚本的整体流程流程分四步读取mcp.source.json。加载环境变量从.env或系统环境。按targets过滤分别渲染 Claude Code 和 Cursor 的配置。写入目标路径并做 Token 瘦身。#!/usr/bin/env node const fs require(fs); const path require(path); const os require(os); const SOURCE path.resolve(mcp.source.json); const env { ...process.env, PROJECT_ROOT: process.cwd() }; function loadSource() { return JSON.parse(fs.readFileSync(SOURCE, utf8)); } function resolvePlaceholders(value, env) { if (Array.isArray(value)) return value.map(v resolvePlaceholders(v, env)); if (value typeof value object) { return Object.fromEntries( Object.entries(value).map(([k, v]) [k, resolvePlaceholders(v, env)]) ); } if (typeof value string) { return value.replace(/\$\{(\w)\}/g, (_, name) { if (!(name in env)) throw new Error(Missing env var: ${name}); return env[name]; }); } return value; } function renderFor(target, servers) { const out { mcpServers: {} }; for (const [name, cfg] of Object.entries(servers)) { if (!cfg.targets.includes(target)) continue; const { targets, description, ...rest } cfg; out.mcpServers[name] resolvePlaceholders(rest, env); } return out; } function writeConfig(filePath, data) { fs.mkdirSync(path.dirname(filePath), { recursive: true }); fs.writeFileSync(filePath, JSON.stringify(data, null, 2)); console.log(Wrote ${filePath}); } const source loadSource(); writeConfig( path.join(os.homedir(), .cursor, mcp.json), renderFor(cursor, source.servers) ); writeConfig( path.join(os.homedir(), .claude, mcp.json), renderFor(claude, source.servers) );把这段存成sync-mcp.js在package.json里加一行{ scripts: { sync-mcp: node sync-mcp.js } }之后每次改完源配置跑npm run sync-mcp就完事。这就是标题里说的一个命令。4.2 Token 瘦身砍掉不必要的上下文MCP 配置影响 Token 的地方主要在 server 的元信息。很多 server 启动后会把自己的 tools 列表和描述注入上下文描述写得越长每轮对话消耗越大。瘦身手段有三个精简 description源配置里的description只给人看渲染时不要写进目标配置。上面脚本里const { targets, description, ...rest }这一行就是在剥离它。按需启用用targets控制哪些 server 进哪个客户端。不常用的 server 别塞进去少一个 server 就少一份 tools schema。合并同类 server比如 filesystem 和另一个文件相关 server 功能重叠合并成一个减少工具数量。实测下来一个配置了 10 个 server 的环境砍掉 4 个不常用的、精简描述后单轮对话的上下文 Token 能降 20% 到 30%。这个数字因 server 而异但方向是确定的上下文里每多一个工具定义都是持续成本。4.3 验证同步结果写完配置别急着用先验证。Claude Code 用claude mcp list看 server 是否被识别Cursor 在设置面板的 MCP 区域看连接状态。如果某个 server 显示未连接按这个顺序排查目标 JSON 是否生成成功文件存在且格式正确。占位符是否都替换成了实际值别留${}。command对应的程序是否在 PATH 里npx、node、uvx等。args顺序是否正确。注意Claude Code 和 Cursor 读取配置的时机不同改完配置后 Claude Code 可能需要重启会话Cursor 一般会自动重载。别改完没生效就以为脚本写错了。5. 踩过的坑与排查链路同步脚本本身不复杂但实际用起来会遇到一些意料之外的问题。这一节把几个高频坑和排查过程完整还原方便你对照复现。5.1 路径里的空格和特殊字符macOS 上项目路径经常带空格比如/Users/me/My Projects。如果源配置里直接写这个路径渲染进args数组后某些 server 会把空格当参数分隔符导致路径被截断。解决办法是路径不要手动拼进 args 字符串而是作为独立数组元素args: [-y, modelcontextprotocol/server-filesystem, ${PROJECT_ROOT}]这样渲染后PROJECT_ROOT是数组里的一个独立元素空格不会被误解。如果某个 server 要求路径作为单个字符串参数传入那就得在脚本里做引号包裹但这种情况少见。5.2 环境变量在 GUI 应用里读不到这是最隐蔽的坑。你在终端里export DATABASE_URL...然后跑同步脚本配置渲染正确。但 Cursor 是 GUI 应用它启动 MCP server 时继承的是系统环境不是你终端里的环境。结果就是终端里测试正常Cursor 里 server 起不来。排查链路先确认 Cursor 里 server 的报错信息通常是connection failed或spawn error。检查渲染后的mcp.json里env字段是否真的有值。如果源配置用了${DATABASE_URL}而 Cursor 环境里没有这个变量渲染时就会报错——但如果你是在终端渲染的渲染结果是正确的问题出在 Cursor 启动 server 时拿不到这个值。解决方式有两种一是把敏感值直接写进渲染后的配置不推荐但简单二是用.env文件配合 server 自己加载需要 server 支持。我个人的做法是非敏感配置直接渲染成字面量敏感值走 server 自己的配置文件避免依赖 GUI 应用的环境继承。5.3 两端 server 名字冲突Claude Code 和 Cursor 对 server 名字的约束不同。有些名字在 Cursor 里能用在 Claude Code 里因为包含特殊字符被拒。源配置里统一用小写字母加连字符命名比如my-server别用下划线、空格或大写能避开大部分命名问题。5.4 同步后旧配置残留脚本是覆盖写入但如果目标文件之前有脚本不认识的 server比如你手动加的覆盖后就丢了。建议脚本在写入前先备份一份function writeConfig(filePath, data) { if (fs.existsSync(filePath)) { fs.copyFileSync(filePath, filePath .bak); } fs.mkdirSync(path.dirname(filePath), { recursive: true }); fs.writeFileSync(filePath, JSON.stringify(data, null, 2)); }这样万一同步出问题还能从.bak恢复。等确认稳定了再考虑去掉备份逻辑。6. 把这套方案用顺手的几个经验方案跑通只是开始真正让它成为日常习惯还需要一些细节上的打磨。这一节分享几个我在实际使用中总结的经验都是文档里不会写的。6.1 源配置按用途分组server 多了以后源配置会变得很长。建议按用途分组比如文件类、数据库类、API 类每组之间用注释或空行隔开。JSON 不支持注释但可以用一个_comment字段占位{ servers: { _comment_filesystem: 文件相关, filesystem: { ... }, postgres: { ... } } }渲染时脚本会自动跳过以_开头的 key不影响目标配置。6.2 给同步命令加个 watch 模式每次改完源配置手动跑命令有点烦。可以用nodemon或 Node 自带的fs.watch监听源文件变化自动触发同步fs.watch(SOURCE, () { console.log(Source changed, re-syncing...); main(); });这样改完保存两端配置自动更新体验顺滑很多。不过 watch 模式在 CI 环境里别开会一直挂着。6.3 Token 用量要定期复盘Token 瘦身不是一次性的。随着你接入更多 server上下文会慢慢膨胀。建议每隔一段时间用客户端的用量统计看一眼找出那些装了但几乎没用的 server果断从targets里移除。我自己的习惯是每月清一次把过去一个月没调用过的 server 下线。6.4 团队协作时的约定如果团队多人用同一套 MCP 配置源配置进 Git 后要约定几件事占位符命名统一都用大写加下划线、targets字段必填、新增 server 要在 PR 里说明用途。否则源配置会变成一团乱麻同步脚本也救不了。6.5 别忘了客户端本身的更新Claude Code 和 Cursor 都在快速迭代MCP 配置格式偶尔会变。同步脚本要留出适配空间比如把渲染逻辑按客户端拆成独立函数格式变了只改对应函数不影响另一边。我一般会在客户端大版本更新后先手动配一个 server 验证格式再更新脚本。这套方案从最初的手动复制粘贴到现在的一条命令同步中间迭代了好几版。最深的体会是配置管理的价值不在于省下那几分钟而在于消除两边不一致带来的隐性成本。当你知道两端配置永远同步、Token 用量可控时才能把精力真正放在用 MCP 解决问题上而不是维护配置本身。
阅读完成 · 觉得有帮助？
