1. 手动维护 MCP 配置到底烦在哪如果你同时用 Claude Code 和 Cursor又刚好在几个项目之间来回切换那你大概率经历过这样的场景在 A 项目里配好的 MCP 服务器换到 B 项目要重新抄一遍 JSON在 Cursor 的mcp.json里加了一个文件系统服务转头又得去 Claude Code 的配置文件里再写一遍。写错一个逗号、漏掉一个转义符整个配置直接失效排查半天才发现是 JSON 语法问题。MCP全称 Model Context Protocol是让 AI 编程工具能够调用外部能力的一套协议。你可以把它理解成给 AI 装外设的接口标准——文件读写、数据库查询、浏览器操作、第三方 API 调用都通过 MCP 服务器暴露给 AI 客户端。Claude Code 和 Cursor 都支持 MCP但两者的配置文件位置、字段格式、启动方式各有差异这就导致同一个 MCP 服务器要在多个地方重复声明。更麻烦的是 Token 消耗。MCP 服务器的工具描述、参数 schema 都会作为上下文注入到对话里。如果你挂了一堆用不上的 MCP 服务器每次对话都在为这些无关的工具定义付费。实测下来一个配置臃肿的 MCP 列表光工具描述就能吃掉几千个 Token 的上下文预算这在长对话里是实打实的成本。这篇内容要解决的就是配置同步和Token 浪费这两个痛点。核心思路是用一个命令行工具把 MCP 服务器的定义集中管理然后一条命令同步到 Claude Code、Cursor 以及其他支持 MCP 的客户端同时按项目按需启用避免无关工具占用上下文。适合所有已经在用或准备用 MCP 的开发者不管你是刚接触 Claude Code 的新手还是已经在多个客户端之间手动同步配置的老手。2. 先搞清楚 MCP 配置在两端到底长什么样在动手做自动化之前必须先把 Claude Code 和 Cursor 各自的配置格式摸清楚。很多人一上来就想写脚本结果连目标格式都没搞明白同步出来的配置根本跑不起来。2.1 Claude Code 的 MCP 配置结构Claude Code 的 MCP 配置通常放在用户级或项目级的配置文件中。用户级配置对所有项目生效项目级配置只对当前目录生效。一个典型的配置长这样{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/dir], env: {} }, sqlite: { command: uvx, args: [mcp-server-sqlite, --db-path, ./data.db] } } }关键字段是command、args和env。command是启动命令args是参数数组env是环境变量。注意args必须是数组不能写成字符串这是最常见的格式错误之一。2.2 Cursor 的 MCP 配置差异Cursor 的 MCP 配置放在.cursor/mcp.json项目级或全局配置目录下。格式和 Claude Code 高度相似但有几个细节差异容易踩坑对比项Claude CodeCursor配置文件名用户级/项目级配置文件.cursor/mcp.json顶层字段mcpServersmcpServers命令字段commandargscommandargs环境变量env对象env对象传输方式stdio / SSEstdio / SSE项目级覆盖支持支持看起来几乎一样对吧但实际差异在于Cursor 对某些字段的容错更严格比如args里如果混入了未转义的路径分隔符在 Windows 上会直接报错而 Claude Code 对相对路径的解析基准目录和 Cursor 不同同一个./data.db在两个客户端里可能指向不同的绝对路径。2.3 为什么不能简单复制粘贴有人会想既然格式差不多那我写一份配置两边复制不就行了问题在于路径基准不同Claude Code 的项目级配置以项目根目录为基准Cursor 的.cursor/mcp.json也以项目根为基准但如果你用的是用户级配置基准就变成了用户主目录相对路径全部失效。命令可用性不同Claude Code 内置了npx和uvx的调用环境Cursor 在某些版本里需要你显式指定完整路径。启用范围不同你可能希望某个 MCP 服务器只在特定项目里对 Claude Code 启用但对 Cursor 全局启用这种差异化需求靠复制粘贴根本做不到。所以真正需要的不是复制而是集中定义 按目标生成。这就是自动化同步工具要解决的核心问题。3. 用一份源配置驱动多端同步的实现思路核心设计原则只有一条单一数据源多端生成。你只维护一份 MCP 服务器清单工具负责把它转换成各个客户端需要的格式并写到正确的位置。3.1 源配置的字段设计源配置需要比目标格式多几个字段用来描述这个服务器该同步到哪些客户端在哪些项目里启用。我用的结构是这样的{ servers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ${PROJECT_ROOT}], env: {}, targets: [claude, cursor], scope: project, tags: [core, file] }, sqlite: { command: uvx, args: [mcp-server-sqlite, --db-path, ${PROJECT_ROOT}/data.db], targets: [claude], scope: project, tags: [data] } } }几个关键设计点targets决定同步到哪些客户端[claude, cursor]表示两端都写。scope决定写到项目级还是用户级project写项目配置global写用户配置。tags用于按需启用比如你只想在数据分析项目里启用data标签的服务器。${PROJECT_ROOT}是占位符生成时替换成实际项目路径解决相对路径基准不一致的问题。3.2 路径占位符的替换逻辑路径问题是跨客户端同步最容易翻车的地方。我的做法是在生成阶段做占位符替换而不是依赖客户端的相对路径解析。具体规则读取源配置时扫描所有args和env值中的${PROJECT_ROOT}。根据scope决定替换值project用当前项目根目录的绝对路径global用用户主目录。替换后的路径统一使用正斜杠Windows 下也先转成正斜杠再由客户端自己处理。这样做的好处是无论客户端怎么解析相对路径你传进去的都是绝对路径行为完全可预测。3.3 生成目标文件的完整流程整个同步流程分四步定位项目根从当前工作目录向上查找.git或package.json找到项目根。找不到就用当前目录。加载源配置从~/.mcp-sync/servers.json读取集中定义。过滤与替换按targets和tags过滤出需要同步的服务器替换占位符。写入目标按scope写到 Claude Code 和 Cursor 对应的配置文件写入前先备份原文件。写入时有个细节要注意不要直接覆盖整个文件而是做合并写入。因为客户端自己可能也会往配置里写东西比如你在 Cursor 界面里手动加了一个服务器直接覆盖会把这些改动冲掉。合并策略是以源配置为准更新同名服务器保留目标文件里源配置没有的条目。4. 一条命令跑通同步的实操步骤下面是从零开始把整套流程跑起来的完整步骤。假设你已经装好了 Node.js 环境。4.1 初始化源配置目录mkdir -p ~/.mcp-sync touch ~/.mcp-sync/servers.json然后把前面那份源配置结构写进servers.json。第一次可以先只放一个filesystem服务器跑通了再加其他的。4.2 编写同步脚本的核心逻辑脚本用 Node.js 写因为 Claude Code 和 Cursor 生态里 Node 最通用。核心逻辑大概一百多行关键部分如下const fs require(fs); const path require(path); const os require(os); function findProjectRoot(startDir) { let dir startDir; while (dir ! path.dirname(dir)) { if (fs.existsSync(path.join(dir, .git)) || fs.existsSync(path.join(dir, package.json))) { return dir; } dir path.dirname(dir); } return startDir; } function replacePlaceholders(value, projectRoot) { if (typeof value string) { return value.replace(/\$\{PROJECT_ROOT\}/g, projectRoot); } if (Array.isArray(value)) { return value.map(v replacePlaceholders(v, projectRoot)); } if (value typeof value object) { const out {}; for (const [k, v] of Object.entries(value)) { out[k] replacePlaceholders(v, projectRoot); } return out; } return value; } function buildServerConfig(server, projectRoot) { return { command: server.command, args: replacePlaceholders(server.args, projectRoot), env: replacePlaceholders(server.env || {}, projectRoot) }; }这段代码的关键是replacePlaceholders的递归处理因为args是数组env是对象占位符可能出现在任意层级。4.3 写入 Claude Code 配置Claude Code 的项目级配置路径需要根据你的实际安装方式确认。写入逻辑function writeClaudeConfig(servers, projectRoot, scope) { const configPath scope project ? path.join(projectRoot, .claude, settings.json) : path.join(os.homedir(), .claude, settings.json); const existing fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, utf8)) : {}; existing.mcpServers existing.mcpServers || {}; for (const [name, server] of Object.entries(servers)) { existing.mcpServers[name] buildServerConfig(server, projectRoot); } fs.mkdirSync(path.dirname(configPath), { recursive: true }); fs.writeFileSync(configPath, JSON.stringify(existing, null, 2)); }注意mkdirSync的recursive: true否则目录不存在时会报错。4.4 写入 Cursor 配置Cursor 的写入逻辑几乎一样只是路径不同function writeCursorConfig(servers, projectRoot, scope) { const configPath scope project ? path.join(projectRoot, .cursor, mcp.json) : path.join(os.homedir(), .cursor, mcp.json); const existing fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, utf8)) : {}; existing.mcpServers existing.mcpServers || {}; for (const [name, server] of Object.entries(servers)) { existing.mcpServers[name] buildServerConfig(server, projectRoot); } fs.mkdirSync(path.dirname(configPath), { recursive: true }); fs.writeFileSync(configPath, JSON.stringify(existing, null, 2)); }4.5 加一个命令行入口把上面的逻辑串起来加一个简单的 CLIconst args process.argv.slice(2); const tags args.filter(a a.startsWith(--tag)).map(a a.split()[1]); const projectRoot findProjectRoot(process.cwd()); const source JSON.parse(fs.readFileSync( path.join(os.homedir(), .mcp-sync, servers.json), utf8 )); const filtered {}; for (const [name, server] of Object.entries(source.servers)) { if (tags.length !server.tags.some(t tags.includes(t))) continue; filtered[name] server; } const claudeServers {}; const cursorServers {}; for (const [name, server] of Object.entries(filtered)) { if (server.targets.includes(claude)) claudeServers[name] server; if (server.targets.includes(cursor)) cursorServers[name] server; } if (Object.keys(claudeServers).length) { writeClaudeConfig(claudeServers, projectRoot, project); } if (Object.keys(cursorServers).length) { writeCursorConfig(cursorServers, projectRoot, project); } console.log(Synced ${Object.keys(filtered).length} servers.);跑起来就是node sync-mcp.js --tagcore这条命令会把所有带core标签的服务器同步到 Claude Code 和 Cursor 的项目级配置里。5. 省 Token 的关键按需启用而不是全量挂载配置同步只是第一步真正省 Token 的是按需启用。很多人 MCP 配置一多每次对话上下文里塞满了用不到的工具描述Token 哗哗地烧。5.1 MCP 工具描述到底吃多少 Token一个典型的 MCP 服务器会暴露 5 到 20 个工具每个工具的描述加参数 schema 大概 100 到 300 Token。挂 5 个服务器光工具定义就可能占掉 3000 到 8000 Token。在 Claude Code 这种长对话场景里这部分是每轮都要重新计算的累积成本很可观。我实测过一个对比同一个项目全量挂载 6 个 MCP 服务器 vs 只挂载当前任务需要的 2 个单轮对话的输入 Token 差了将近 40%。对于需要反复迭代的编程任务这个差距会迅速放大。5.2 用标签做项目级隔离前面源配置里的tags字段就是为这个设计的。你可以给服务器打上core、data、web、browser等标签然后在不同项目里只同步需要的标签。比如一个纯后端项目只需要core和datanode sync-mcp.js --tagcore --tagdata一个前端项目需要core和browsernode sync-mcp.js --tagcore --tagbrowser这样每个项目的 MCP 配置都是精简的不会互相污染。5.3 会话级动态开关的思路更激进的做法是会话级开关。Claude Code 支持在对话中动态调整 MCP 服务器你可以把同步脚本和会话启动脚本结合在启动时根据当前任务类型决定挂哪些服务器。我的做法是在项目根放一个.mcp-tags文件内容就是标签列表core data同步脚本读取这个文件自动决定同步哪些服务器。这样你连命令行参数都不用记进项目跑一次同步就行。6. 踩过的坑和排查思路这套流程我迭代了好几版踩的坑不少挑几个典型的说说。6.1 JSON 合并时数组被覆盖最开始我用的合并逻辑是Object.assign结果发现args数组被整个替换了。后来改成深合并但深合并又带来新问题如果源配置里删掉了一个参数目标文件里的旧参数不会被清除。最终的方案是同名服务器整体替换不同名服务器保留。这样源配置是唯一真相目标文件里只保留源配置没有的条目。6.2 Windows 路径分隔符导致启动失败在 Windows 上args里的路径如果用了反斜杠JSON 里需要转义成\\很容易漏。我的处理是在生成阶段统一把路径转成正斜杠Node.js 的path模块在 Windows 上也能正确处理正斜杠。实测下来npx和uvx都能接受正斜杠路径。6.3 环境变量在不同客户端行为不一致env字段里的变量Claude Code 和 Cursor 的注入时机不同。有些客户端在启动 MCP 服务器时才注入有些在配置加载时就读取。如果你的 MCP 服务器依赖环境变量做初始化最好在command里显式传递而不是依赖env。比如{ command: env, args: [API_KEYxxx, npx, -y, some-mcp-server] }这样虽然丑一点但行为最可预测。6.4 同步后客户端没生效最常见的原因是客户端缓存了旧配置。Claude Code 和 Cursor 都需要重启或者重新加载窗口才能读取新的 MCP 配置。我的习惯是同步完直接重启客户端别指望热加载。另外如果配置文件路径写错了客户端不会报错只是静默使用旧配置所以同步脚本最好打印出实际写入的路径方便核对。6.5 排查清单遇到同步后不生效按这个顺序查检查项排查方法配置文件路径脚本打印的路径和客户端实际读取的路径是否一致JSON 语法用JSON.parse验证或在线 JSON 校验工具命令可用性手动在终端跑一遍commandargs看能否启动路径正确性检查替换后的绝对路径是否存在客户端重启完全退出客户端再重新打开权限问题配置文件是否有写权限MCP 服务器是否有执行权限7. 把这套方案扩展到更多客户端MCP 生态在快速扩张除了 Claude Code 和 Cursor还有不少工具开始支持 MCP。这套单一数据源 多端生成的思路可以很容易扩展。7.1 新增一个客户端的成本新增客户端只需要做三件事在源配置的targets里加上新客户端的标识。写一个对应的writeXxxConfig函数处理该客户端的路径和格式差异。在 CLI 入口里加一个分支。大部分客户端用的都是mcpServers这个顶层字段格式差异主要在路径和少量字段名上。所以扩展成本很低基本半小时能搞定一个新客户端。7.2 用适配器模式统一格式如果客户端多了建议引入适配器模式。每个客户端一个适配器对象包含configPath(scope, projectRoot)和transform(server)两个方法。主流程只负责过滤和替换具体格式转换交给适配器。这样新增客户端不用改主流程只加一个适配器文件就行。7.3 版本管理与回滚源配置建议用 Git 管理放在~/.mcp-sync目录下初始化一个仓库。每次改动都有记录同步出问题可以快速回滚。另外同步脚本在写入前会自动备份目标文件到.bak万一合并逻辑出问题还能手动恢复。7.4 和团队共享配置如果是团队协作可以把源配置放在项目仓库里比如.mcp-servers.json然后同步脚本优先读项目内的配置读不到再读用户级的。这样新成员克隆项目后跑一次同步就能获得和团队一致的 MCP 环境省去大量沟通成本。8. 一些实际使用中的体会这套方案我用了几个月最大的感受是配置管理这件事自动化一次省心很久。以前每换一个项目就要重新配 MCP现在进项目跑一条命令Claude Code 和 Cursor 同时就绪而且只挂当前项目需要的服务器Token 消耗肉眼可见地降下来了。有个小技巧值得分享把同步命令加到项目的package.json的scripts里比如sync-mcp: node ~/.mcp-sync/sync.js --tagcore这样团队成员不用记脚本路径跑npm run sync-mcp就行。另外源配置里的服务器定义建议加注释字段虽然 JSON 不支持注释但可以加一个_comment字段记录这个服务器是干什么的、为什么这么配。过几个月回头看没有注释的配置基本等于天书。最后提醒一点MCP 服务器的command和args一定要手动验证一遍能启动再写进源配置。我遇到过好几次是 MCP 包本身版本更新导致启动参数变了同步脚本没问题但服务器起不来排查半天才发现是上游变更。养成先手动跑通再写进配置的习惯能省很多时间。