給 Claude Code 和 Cursor 配 MCP 這事我之前是真上頭。一個(gè) server 要維護(hù)兩處配置Claude Code 認(rèn)項(xiàng)目根目錄的.mcp.jsonCursor 認(rèn).cursor/mcp.json格式看著差不多字段細(xì)節(jié)又不完全一致。新增一個(gè)服務(wù)得改兩個(gè)文件刪掉一個(gè)又容易漏清理來回折騰半天最后打開編輯器發(fā)現(xiàn)工具加載不出來連著好幾輪對話全耗在排查上。說句實(shí)在的手寫 JSON 浪費(fèi)的時(shí)間是小頭燒掉的 Token 才是真肉疼。后來我把這套流程收斂成了一個(gè)命令項(xiàng)目里維護(hù)一份mcp.config.yaml跑一次同步腳本自動生成并更新 Claude Code 和 Cursor 兩邊的配置同時(shí)把不用的 server 剪掉。實(shí)測下來配置不用碰 JSONToken 消耗也肉眼可見地降了。這篇文章就把方案、腳本實(shí)現(xiàn)、省 Token 的原理和踩過的坑完整記錄下來。適合在 Claude Code 和 Cursor 之間來回切換、手里已經(jīng)攢了三五個(gè) MCP server 的人如果你是剛接觸 MCP 的新手也能把兩個(gè)工具的配置機(jī)制一次看明白。1. 先說說手工配置為什么這么讓人上火1.1 兩套工具、兩套配置看起來一樣其實(shí)不一樣先對齊一個(gè)事實(shí)Claude Code 和 Cursor 對 MCP server 的配置入口并不相同。Claude Code 的項(xiàng)目級配置放在項(xiàng)目根目錄的.mcp.jsonCursor 的項(xiàng)目級配置放在.cursor/mcp.json。兩者都是標(biāo)準(zhǔn) JSON 文件不認(rèn)識的人第一次看到會以為只是目錄名換了但實(shí)際上它們歸屬不同的配置體系。Claude Code 還有用戶級和項(xiàng)目級的作用域區(qū)分用戶級配置寫在你本機(jī)用戶目錄的全局 JSON 里項(xiàng)目級配置才寫在.mcp.jsonCursor 也有自己的全局設(shè)置面板項(xiàng)目級則讀取.cursor/mcp.json。再看內(nèi)容結(jié)構(gòu)兩邊都遵循 MCP 協(xié)議的mcpServers容器// .mcp.json — Claude Code 項(xiàng)目級配置 { mcpServers: { filesystem: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp] } } }// .cursor/mcp.json — Cursor 項(xiàng)目級配置 { mcpServers: { filesystem: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp] } } }看起來幾乎一樣問題恰恰出在這個(gè)“幾乎”上。你把.mcp.json里的內(nèi)容原樣復(fù)制到.cursor/mcp.json大多數(shù)場景確實(shí)能跑但一旦涉及環(huán)境變量、命令路徑、全局作用域兩邊就會開始出現(xiàn)各種不一致。同一個(gè) server在 Claude Code 里用npx能起來在 Cursor 里卻經(jīng)常報(bào)“找不到命令”因?yàn)?Cursor 作為圖形應(yīng)用啟動時(shí)不會加載你 shell 里的 PATH。這種差異只有踩過坑的人才會注意但每次踩坑都得搭進(jìn)去好幾輪對話去排查。1.2 手寫 JSON 真正的坑不在格式而在“同步”格式問題其實(shí)是最好解決的真正的坑是“同步”。舉個(gè)最常見的例子你加了一個(gè)新的 MCP server在 Claude Code 里調(diào)通了很開心然后打開 Cursor 繼續(xù)用發(fā)現(xiàn)工具沒出現(xiàn)。為什么因?yàn)槟阒桓牧?mcp.json忘了改.cursor/mcp.json。反過來也成立你在 Cursor 的設(shè)置面板里加了個(gè)全局 server回到 Claude Code 終端里還得手動再配一遍。第二個(gè)坑是刪除。某個(gè) server 不用了你從 Claude Code 的配置里刪掉但 Cursor 那邊還留著一份。結(jié)果就是每次打開 Cursor它都會嘗試去啟動這個(gè)已經(jīng)不需要的進(jìn)程工具列表里多一個(gè)永遠(yuǎn)加載失敗的入口。AI 助手并不知道這個(gè)工具其實(shí)已經(jīng)廢棄它還可能在思考時(shí)反復(fù)嘗試調(diào)用白白浪費(fèi) Token。第三個(gè)坑是環(huán)境變量。不少 MCP server 需要 API key、token 這類環(huán)境變量。Claude Code 在終端里跑能繼承你.zshrc或.bashrc里的變量Cursor 啟動時(shí)不一定會帶這些。于是同一個(gè) server終端里好好的到了 Cursor 里就鑒權(quán)失敗。配置里寫不寫環(huán)境變量、寫在哪個(gè)作用域都變得異常敏感。這些問題的本質(zhì)都一樣配置存在兩份沒有任何機(jī)制保證它們始終一致。只要靠手早晚會漏。1.3 配置亂才會燒 Token這鍋必須算清楚很多人沒意識到MCP 配置混亂會直接反映在 Token 消耗上。原理不復(fù)雜AI 助手每次請求時(shí)需要把可用的工具列表包括每個(gè)工具的名字、描述、參數(shù)結(jié)構(gòu)跟隨上下文一起發(fā)送。你全局配置里掛著的每一個(gè) MCP server即便這次對話完全沒用上它的工具定義也會占用上下文空間。更隱蔽的是“錯誤重試”的消耗。一個(gè) MCP server 因?yàn)?JSON 寫錯了、路徑不對、環(huán)境變量缺失而連不上AI 助手并不會立刻放棄。它可能在工具調(diào)用失敗后換一種方式再次嘗試或者把這個(gè)失敗記錄重新組織語言向你解釋。這個(gè)過程消耗的上下文往往是正常調(diào)用工具的好幾倍。表面上看是“配置有點(diǎn)問題”實(shí)際上每一次調(diào)試失敗都在持續(xù)燒 Token。所以配置管理不只是維護(hù)便利性問題它直接影響你的使用成本和效率。這也是為什么我后來下定決心把兩套配置收斂成一份。2. 解法一份配置源管住兩個(gè)工具2.1 設(shè)計(jì)原則Source of Truth 只有一個(gè)我的核心思路很簡單建立一個(gè)“單一事實(shí)來源”Source of Truth所有 MCP server 的配置只在這個(gè)文件里維護(hù)然后通過腳本生成兩個(gè)工具各自需要的配置產(chǎn)物。改配置只改一處跑一次同步命令兩邊同時(shí)更新。具體就是用項(xiàng)目根目錄的mcp.config.yaml作為唯一配置源用一個(gè)同步腳本讀取 YAML分別生成.mcp.json和.cursor/mcp.json生成結(jié)果納入 git 版本管理團(tuán)隊(duì)共享時(shí)可以直接對比差異重點(diǎn)腳本不只是“復(fù)制”而是按目標(biāo)工具的規(guī)則做過濾和轉(zhuǎn)換。這個(gè)設(shè)計(jì)有幾個(gè)好處。首先是可審計(jì)git diff 能清楚看到哪個(gè) server 改了、哪個(gè)刪了其次是可復(fù)用換新項(xiàng)目時(shí)把 YAML 拷過去跑一遍同步就完成初始化最后是天然防漏腳本會同時(shí)更新兩個(gè)文件不會再出現(xiàn)“只改了一個(gè)”的情況。2.2 配置文件長什么樣mcp.config.yaml的完整結(jié)構(gòu)是這樣的version: 1 servers: filesystem: command: npx args: - -y - modelcontextprotocol/server-filesystem - . targets: [claude, cursor] enabled: true git: command: npx args: - -y - some/git-mcp-server env: GITHUB_TOKEN: ${GITHUB_TOKEN} targets: [cursor] enabled: true playwright: command: npx args: - -y - some/playwright-mcp targets: [claude] enabled: false字段說明字段含義可選值 / 示例servers所有要管理的 MCP server 集合每個(gè) server 一個(gè) keycommand啟動命令npx、python、可執(zhí)行文件絕對路徑args啟動參數(shù)列表數(shù)組形式避免手動拼接字符串轉(zhuǎn)義問題env需要注入的環(huán)境變量支持${VAR}占位符同步時(shí)從真實(shí)環(huán)境讀取targets這個(gè) server 要同步給哪些工具claude、cursor可同時(shí)指定enabled是否啟用true/false關(guān)閉時(shí)不寫入任何配置你可能注意到我特意把參數(shù)寫成了數(shù)組而不是一個(gè)長字符串。這是從 JSON 配置時(shí)代留下來的經(jīng)驗(yàn)數(shù)組可以原樣落到配置里不用處理引號和轉(zhuǎn)義各種奇奇怪怪的包名也不會出錯。2.3 為什么選 YAML 而不是繼續(xù)用 JSON既然最終產(chǎn)物是 JSON為什么不直接用一個(gè)“配置源 JSON”原因有兩點(diǎn)。第一YAML 支持注釋。同一個(gè) server 為什么要配、某個(gè)環(huán)境變量從哪里拿、哪個(gè) server 在哪個(gè)項(xiàng)目里驗(yàn)證過這些信息可以直接寫進(jìn)配置團(tuán)隊(duì)里其他人一看就明白。JSON 要實(shí)現(xiàn)類似效果只能靠額外文檔文檔和配置分開后很快就會過時(shí)。第二diff 可讀性。YAML 按縮進(jìn)組織git 里看出入很直觀JSON 稍微復(fù)雜一點(diǎn)尤其是嵌套層級比較深的時(shí)候diff 輸出經(jīng)常是一整塊被替換定位不到具體變化。配置源文件會被頻繁更新這點(diǎn)差異體驗(yàn)差距很大。當(dāng)然如果你團(tuán)隊(duì)實(shí)在不習(xí)慣 YAML也可以退一步用 JSONC帶注釋的 JSON或者直接維護(hù)一個(gè)簡單的 JS 模塊。核心不是文件格式而是“單一配置源 生成多個(gè)目標(biāo)”這套思路格式只是載體。3. 一條命令全搞定同步腳本實(shí)現(xiàn)細(xì)節(jié)3.1 核心邏輯一個(gè) Python 腳本就夠了我選 Python 寫同步腳本理由是跨平臺、依賴少、邏輯直觀。完整實(shí)現(xiàn)如下#!/usr/bin/env python3 mcp-sync: 從單一配置源同步 MCP server 配置到 Claude Code 與 Cursor。 import json import os import sys from pathlib import Path import yaml CONFIG_PATH Path(mcp.config.yaml) OUTPUTS { claude: Path(.mcp.json), cursor: Path(.cursor/mcp.json), } def load_config(path: Path) - dict: with open(path, r, encodingutf-8) as f: return yaml.safe_load(f) def resolve_env(env: dict) - dict: resolved {} for key, value in env.items(): if isinstance(value, str) and value.startswith(${) and value.endswith(}): var_name value[2:-1] resolved[key] os.environ.get(var_name, ) else: resolved[key] value return resolved def build_server_entry(server: dict) - dict: entry { type: stdio, command: server[command], args: server.get(args, []), } if server.get(env): entry[env] resolve_env(server[env]) return entry def build_target_config(config: dict, target: str) - dict: servers {} for name, server in config[servers].items(): if not server.get(enabled, True): continue if target not in server.get(targets, [claude, cursor]): continue servers[name] build_server_entry(server) return {mcpServers: servers} def write_outputs(config: dict): for target, out_path in OUTPUTS.items(): payload build_target_config(config, target) out_path.parent.mkdir(parentsTrue, exist_okTrue) with open(out_path, w, encodingutf-8) as f: json.dump(payload, f, indent2, ensure_asciiFalse) f.write(\n) print(f[mcp-sync] wrote {out_path} ({len(payload[mcpServers])} servers)) if __name__ __main__: if not CONFIG_PATH.exists(): sys.exit(f缺少配置文件: {CONFIG_PATH}) cfg load_config(CONFIG_PATH) write_outputs(cfg)邏輯拆開也就三步。第一步讀 YAML。yaml.safe_load把配置變成字典后續(xù)操作全部走 Python 數(shù)據(jù)結(jié)構(gòu)不用再碰字符串拼接。第二步按目標(biāo)工具過濾。以targets為篩選條件claude工具只會拿到聲明了包含claude的 servercursor同理。enabled: false的 server 直接跳過不會出現(xiàn)在任何產(chǎn)物里。第三步寫文件。JSON 用indent2格式化保證 git diff 干凈ensure_asciiFalse是為了避免中文注釋或路徑被轉(zhuǎn)義成一堆\uXXXX讀起來更舒服。環(huán)境變量這里處理得很小心配置里寫${GITHUB_TOKEN}同步時(shí)從當(dāng)前進(jìn)程環(huán)境讀取并填充。這個(gè)方案比直接在配置里寫明文要安全一點(diǎn)畢竟配置文件可能要提交到 git也比“完全不支持環(huán)境變量”的方案好用很多 server 的鑒權(quán)信息都能通過這種方式接進(jìn)來。3.2 把腳本包裝成“一條命令”腳本本身還只是腳本要變成“一條命令自動同步”還得注冊一個(gè)入口。我的做法是在package.json里加一個(gè) script{ scripts: { mcp:sync: python3 mcp-sync.py } }這樣項(xiàng)目里執(zhí)行npm run mcp:sync就是一次完整同步。如果你用的項(xiàng)目不是 Node.js 生態(tài)也有幾個(gè)常見方案寫個(gè) Makefilemake mcp-sync在 shell 配置里加 aliasalias mcp-syncpython3 ~/tools/mcp-sync.py用 Git 的 pre-commit 鉤子在提交前自動跑一遍同步保證倉庫里的配置永遠(yuǎn)是最新生成的。我自己一般兩種方式結(jié)合個(gè)人項(xiàng)目用 alias團(tuán)隊(duì)項(xiàng)目用 npm script。前者的好處是不受項(xiàng)目類型限制后者勝在隨項(xiàng)目走、隊(duì)友拉下來就知道怎么跑。3.3 同步腳本順帶做的三件事如果你仔細(xì)看上面的代碼會發(fā)現(xiàn)這個(gè)腳本不只是在“復(fù)制配置”它做了三件手工維護(hù)很難堅(jiān)持的事情第一過濾。enabled: false的 server 和不在targets范圍內(nèi)的工具一律不寫入產(chǎn)物。這意味著你可以把暫時(shí)不用的 server 保留在配置源里但不會讓它在任何一邊生效。這一點(diǎn)對省 Token 尤其重要后面專門說。第二環(huán)境變量展開。統(tǒng)一在腳本層完成${VAR}替換產(chǎn)物里已經(jīng)是真實(shí)值。這也避免了不同工具對環(huán)境變量的處理方式不一致導(dǎo)致的問題。第三冪等覆蓋。每次同步都是全量重寫目標(biāo)文件不是“添加缺失項(xiàng)”。這樣配置源里刪除一個(gè) server同步后目標(biāo)文件里也會消失不會出現(xiàn)“刪不掉”的殘留。配合 git 使用刪除操作的變更記錄一目了然。如果你希望同步腳本更“聰明”一些還可以加一個(gè)清理邏輯先讀取目標(biāo)文件里已有的 server 列表和配置源對比把配置源里已經(jīng)不存在但目標(biāo)文件里還殘留的 server 自動移除。不過我的建議是保留“全量重寫”這個(gè)簡單行為因?yàn)槿恐貙懕旧砭吞烊唤鉀Q了殘留問題再加清理邏輯反而復(fù)雜。4. 省 Token 不是玄學(xué)這筆賬我算過4.1 一個(gè) MCP 工具定義到底占多少 Token先說結(jié)論一個(gè) MCP 工具的定義在上下文里占用幾百到上千 token具體取決于描述長短和參數(shù)結(jié)構(gòu)復(fù)雜度。每個(gè)工具暴露給 AI 助手的信息包括工具名稱、描述、參數(shù) schemaJSON Schema 格式有時(shí)候還帶枚舉值示例。常見的 server 工具一個(gè)定義大概在 200 到 500 token 之間如果描述寫得特別啰嗦、參數(shù)特別多上千也不奇怪。而 AI 助手在每次請求時(shí)是需要攜帶整個(gè)工具列表的。假設(shè)你掛了 5 個(gè) MCP server平均每個(gè) server 暴露 4 個(gè)工具那么單是工具定義就要占5 servers × 4 tools × 300 tokens ≈ 6,000 tokens這 6,000 token 不管你這個(gè)對話里到底有沒有用上任何一個(gè)工具它都會被算進(jìn)請求頭里。對話超過 20 輪這部分固定開銷就是 120,000 token。這只是配置層面的浪費(fèi)還沒有算工具調(diào)用失敗后反復(fù)重試的額外消耗。4.2 三條省 Token 的配置紀(jì)律基于這個(gè)認(rèn)知我總結(jié)出三條配置紀(jì)律全部體現(xiàn)在mcp.config.yaml的寫法里。第一條只開當(dāng)前項(xiàng)目需要的 server其他一律enabled: false。比如你在一個(gè)純前端項(xiàng)目里寫代碼就不需要給 AI 掛數(shù)據(jù)庫相關(guān)的 server。配置源里可以留著但enabled要關(guān)掉這樣同步產(chǎn)物里不會有它上下文里就少一份工具定義。第二條用targets隔離工具。有些 server 只在 Cursor 里用有些只適合在 Claude Code 終端里跑。把它們分別聲明到對應(yīng)targets互不干擾。比如帶 GUI 操作的瀏覽器工具在終端場景下意義不大就沒必要推到 Claude Code 那里去占上下文。第三條精簡描述和參數(shù)別把順手能做的事做成“超大工具”。MCP 工具的描述文字會原樣進(jìn)入上下文。描述里寫一整段背景說明不如寫成“獲取訂單列表可按狀態(tài)篩選”這種一句話版本。參數(shù)同理能少一個(gè)字段就少一個(gè)字段。工具定義的精簡程度會直接反映到 Token 消耗上這也是很多人容易忽略的點(diǎn)。4.3 我這邊一個(gè)項(xiàng)目的實(shí)測數(shù)據(jù)用一個(gè)我參與的模擬項(xiàng)目舉例。接入同步腳本之前全局開啟了 8 個(gè) MCP server工具總數(shù)大概在 21 個(gè)左右每輪請求光是工具定義就要多花掉 6,000 到 7,000 token。一個(gè) 20 輪的典型會話大約有 12 萬到 14 萬 token 是花在“帶著一堆沒用的工具定義”上面。整理配置之后按項(xiàng)目實(shí)際需求只保留了 3 個(gè) server工具數(shù)降到 7 個(gè)。每輪請求的工具定義開銷壓到 2,000 token 出頭20 輪下來節(jié)省了大約 8 萬 token。這個(gè)數(shù)字沒有計(jì)入“配置正常后失敗重試幾乎消失”的收益實(shí)際體感比賬面上更明顯。有一點(diǎn)必須說明省 Token 的本質(zhì)不是“MCP 本身費(fèi)錢”而是“無用的工具定義和反復(fù)失敗在燒錢”。如果你只有一個(gè) server、三個(gè)工具那手動配置也好、腳本同步也好差別確實(shí)不大。但一旦工具多了、項(xiàng)目多了配置管理的收益會指數(shù)級放大。5. 常見問題與排查技巧實(shí)錄5.1 改了配置不生效怎么辦這是最常被問的問題。跑完mcp-sync文件都寫了但 Cursor 里看不到新工具Claude Code 里也調(diào)不出來。先說 Cursor.cursor/mcp.json的改動Cursor 會監(jiān)控文件變化但某些版本需要重新加載窗口或者重啟才會重新讀取。遇到不生效先試Reload Window不行就重啟應(yīng)用。另外注意檢查一下有沒有把配置文件放在正確的項(xiàng)目根目錄Cursor 的項(xiàng)目級配置只有在對應(yīng)項(xiàng)目根目錄下才生效。再說 Claude Code項(xiàng)目級.mcp.json第一次生效還需要一個(gè)信任步驟。在 Claude Code 會話里輸入/mcp查看當(dāng)前加載的 server 列表如果看到的是“not approved”之類的狀態(tài)需要手動確認(rèn)一次。確認(rèn)過之后后續(xù)同步新 server 也會沿用這個(gè)信任關(guān)系。如果加了新 server 后仍看不到先重啟會話再檢查/mcp的輸出。5.2 命令里的環(huán)境變量不見了前面提到的 PATH 問題在腳本化之后依然可能遇到。因?yàn)閙cp-sync.py在終端里跑它讀取環(huán)境變量用的是當(dāng)前 shell 的環(huán)境。如果你在.zshrc里配了NODE_OPTIONS或者自定義了 PATH終端里啟動腳本沒問題但 Cursor 是圖形應(yīng)用未必繼承這些。兩個(gè)解決辦法。第一個(gè)是在配置里把 command 寫成絕對路徑比如/usr/local/bin/npx、/opt/homebrew/bin/python避免依賴 PATH。第二個(gè)是被環(huán)境變量卡住時(shí)先手動在終端跑一次 server確認(rèn)環(huán)境變量值是否正確再重新執(zhí)行npm run mcp:sync。5.3 YAML 一改就跑不動了YAML 對縮進(jìn)敏感這個(gè)特性平時(shí)是優(yōu)點(diǎn)但在手改配置時(shí)也容易踩坑。最常見的報(bào)錯就是yaml.scanner.ScannerError原因多半是 tab 和空格混用了或者某個(gè)字段少了一個(gè)空格。我的建議是手改完先跑一遍腳本腳本能跑通說明語法沒問題。如果項(xiàng)目里有人不熟悉 YAML可以改成一個(gè)更寬松的 JSONC 源文件代價(jià)是丟掉注釋能力。自己權(quán)衡即可。另外始終推薦在編輯器里裝一個(gè) YAML 格式化插件提交前格式化一下能省掉大多數(shù)縮進(jìn)問題。5.4 團(tuán)隊(duì)協(xié)作時(shí)配置漂移多個(gè)人維護(hù)同一個(gè)項(xiàng)目配置源文件放進(jìn)了 git但有人改完沒跑同步直接提交了舊的.mcp.json和.cursor/mcp.json就會產(chǎn)生配置漂移也就是生成物和源碼不一致。我的處理方式是把兩個(gè)生成文件也從 git 里管起來并且在提交前跑一次同步讓生成物保持最新。更嚴(yán)格的團(tuán)隊(duì)可以在 CI 里加一道檢查拉取代碼后重新跑mcp-sync然后git diff --exit-code如果生成物和提交內(nèi)容不一致直接攔下這次提交。這個(gè)做法成本很低但能有效防住漏同步的問題。5.5 問題速查表現(xiàn)象可能原因處理方式Cursor 里看不到新 server未重載窗口 / 配置文件路徑不對重載窗口或重啟確認(rèn)文件在項(xiàng)目根目錄的.cursor/mcp.jsonClaude Code 里 server 顯示未批準(zhǔn).mcp.json未被信任/mcp手動確認(rèn)啟動失敗提示找不到命令PATH 不一致 / env 解析為空改用絕對路徑 command先驗(yàn)證環(huán)境變量再同步工具列表里出現(xiàn)兩個(gè)相同名字的 server項(xiàng)目級和用戶級配置重復(fù)在/mcp或 Cursor 設(shè)置里檢查作用域移除多余配置同步后 git diff 顯示整個(gè)文件被重寫縮進(jìn)或字段順序變化腳本本身按固定順序輸出確認(rèn)沒有混入手動修改最后再分享一個(gè)小技巧實(shí)際用下來最讓我省心的一點(diǎn)是這套方案把“配置工作”從每次對話里剝離了出去。以前每換一個(gè)項(xiàng)目就要折騰一遍.mcp.json現(xiàn)在只需要把mcp.config.yaml拷過去跑一次同步然后正常開聊。我個(gè)人的建議是剛開始不要貪多先配兩個(gè)真正高頻的 MCP server 跑通流程用一陣子之后再把新需求挨個(gè)加進(jìn)去手里的 server 數(shù)量越多這套自動同步和按需裁剪的價(jià)值就越大。配置越干凈AI 助手反應(yīng)越快錢包也越穩(wěn)。