1. 為什么團(tuán)隊(duì)內(nèi)部系統(tǒng)總?cè)币粋€(gè) MCP Server你可能已經(jīng)用 Claude Code 連過(guò) Jira、GitHub、Postgres這些現(xiàn)成的 MCP Server 開(kāi)箱即用體驗(yàn)很順。但真正卡住大多數(shù)人的是團(tuán)隊(duì)內(nèi)部那套沒(méi)人寫(xiě) Server 的系統(tǒng)自研工單、私有知識(shí)庫(kù)、內(nèi)部腳本、某個(gè)只有你懂的本地工具。它們沒(méi)有官方 MCP 實(shí)現(xiàn)你只能眼睜睜看著 Claude 在對(duì)話里知道有這個(gè)東西卻沒(méi)法真正調(diào)用。mcp-builder 就是為這個(gè)缺口準(zhǔn)備的。它是 Anthropic 在 anthropics/skills 倉(cāng)庫(kù)里維護(hù)的官方 Skill注意它的定位——不是代碼生成器而是一套工程方法論。它教你的不是復(fù)制粘貼一段模板而是四件事怎么規(guī)劃 tool 的命名和 API 覆蓋范圍、怎么用 FastMCPPython或 MCP SDKTypeScript落地實(shí)現(xiàn)、怎么用 MCP Inspector 單獨(dú)調(diào)試、怎么設(shè)計(jì) Eval 驗(yàn)證 Agent 是否真的會(huì)用你的 Server。我試過(guò)直接手寫(xiě) MCP Server最容易翻車(chē)的地方不是代碼本身而是 tool 的 docstring 寫(xiě)得太隨意導(dǎo)致 Claude 填參數(shù)時(shí)全靠猜。mcp-builder 的價(jià)值就在于把這些隱性規(guī)范顯性化tool 名要有前綴加動(dòng)作、docstring 要說(shuō)清每個(gè)參數(shù)含義、錯(cuò)誤要返回可行動(dòng)文案而不是拋異常、只讀 tool 不寫(xiě)盤(pán)。這些規(guī)則聽(tīng)起來(lái)瑣碎但決定了你的 Server 是能跑還是Agent 真的會(huì)用。這篇聚焦一條完整實(shí)操路徑從零用 FastMCP 搭一個(gè)本地筆記 Server走完腳手架生成、MCP Inspector 調(diào)試、本地聯(lián)調(diào)、接入 Claude Code、對(duì)話驗(yàn)收。全程 80 行 Python任何機(jī)器都能跑通不需要 API Key。適合已經(jīng)會(huì)用 Claude Code、想給自己內(nèi)部工具補(bǔ)一個(gè) MCP 接口的開(kāi)發(fā)者。讀完你能獨(dú)立完成一次端到端跑通而不是停留在知道有這么個(gè)東西。2. 前置準(zhǔn)備安裝 mcp-builder 與 FastMCP 環(huán)境在動(dòng)手寫(xiě) Server 之前先把兩樣?xùn)|西裝好Claude Code 里的 mcp-builder Skill以及本機(jī)的 Python MCP 運(yùn)行環(huán)境。這兩件事分開(kāi)做別混在一起否則后面排錯(cuò)會(huì)很痛苦。先說(shuō) Skill 安裝。在 Claude Code 里分兩條命令走第一條是添加 marketplace/plugin marketplace add anthropics/skills第二條是安裝 example-skills 包mcp-builder 就在這個(gè)包里/plugin install example-skillsanthropic-agent-skills如果你只想裝 mcp-builder 這一個(gè) Skill不想把整個(gè) example-skills 都拉下來(lái)可以用 npx 單獨(dú)裝npx skills add anthropics/skills --skill mcp-builder --agent claude-code裝完之后你在 Claude Code 里就能通過(guò) Skill 的方式調(diào)用 mcp-builder 的規(guī)劃指引。它不會(huì)替你寫(xiě)代碼但會(huì)在你規(guī)劃 tool 命名、設(shè)計(jì) docstring 時(shí)給出規(guī)范建議這部分后面 Phase 1 會(huì)用到。再說(shuō)本機(jī)環(huán)境。寫(xiě) Python 版 Server 需要 Python 3.10 及以上然后裝 mcp 包FastMCP 框架就在里面python --version pip install mcp這里有個(gè)坑要提前說(shuō)pip install mcp 裝到的環(huán)境必須和你后面運(yùn)行 server.py 的 python 是同一個(gè)。很多人機(jī)器上有多個(gè) Python系統(tǒng)自帶、conda、venv裝的時(shí)候用了一個(gè)跑的時(shí)候用了另一個(gè)結(jié)果就是ModuleNotFoundError: No module named mcp。建議直接建一個(gè)干凈的虛擬環(huán)境python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install mcp激活后which pythonWindows 用where python確認(rèn)路徑指向 .venv再往下走。這一步花兩分鐘能省掉后面半小時(shí)的排錯(cuò)。關(guān)于 TaoToken 的前置說(shuō)明本篇的 MCP Server 是純本地 stdio 工具不依賴任何遠(yuǎn)程模型網(wǎng)關(guān)就能跑通 Inspector 和 Claude Code 聯(lián)調(diào)。如果你后續(xù)想把 Server 接到遠(yuǎn)程模型做 Eval或者團(tuán)隊(duì)要共享一個(gè) streamable HTTP 的 Server可以先把 TaoToken 的 API Key 準(zhǔn)備好接入文檔在 https://taotoken.net/api Key 在 https://taotoken.net/api-keys 生成。本地 stdio 這條鏈路不需要它但提前備著不虧。環(huán)境確認(rèn)清單Python 3.10、mcp 包已裝、虛擬環(huán)境已激活、Claude Code 已裝 mcp-builder Skill。四項(xiàng)都打勾進(jìn)入下一步。3. 可復(fù)制配置用 FastMCP 寫(xiě)一個(gè) pocket-notes Server這一節(jié)是全文的核心直接給你可復(fù)制的完整代碼和配置片段。我們做一個(gè) pocket-notes MCP Server功能是讓 Claude 幫你管理本地純文本筆記添加、列表、搜索。數(shù)據(jù)存在用戶目錄的 JSON 文件里不需要 API Key任何機(jī)器都能跑通。先建目錄mkdir pocket-notes-mcp cd pocket-notes-mcp然后創(chuàng)建 server.py下面是完整可運(yùn)行代碼import json from pathlib import Path from mcp.server.fastmcp import FastMCP mcp FastMCP(pocket-notes) NOTES_FILE Path.home() / .pocket-notes / notes.json def _load(): if not NOTES_FILE.exists(): return [] return json.loads(NOTES_FILE.read_text(encodingutf-8)) def _save(notes): NOTES_FILE.parent.mkdir(parentsTrue, exist_okTrue) NOTES_FILE.write_text( json.dumps(notes, ensure_asciiFalse, indent2), encodingutf-8) mcp.tool() def notes_add(title: str, content: str) - str: Add a note. title: note title; content: note body. title title.strip() if not title: return Error: title cannot be empty. Provide a title and retry. notes _load() note_id len(notes) 1 notes.append({id: note_id, title: title, content: content.strip()}) _save(notes) return fAdded note #{note_id}: {title} mcp.tool() def notes_list() - str: List all notes (id and title only). notes _load() if not notes: return No notes yet. Use notes_add first. return \n.join(f#{n[id]} {n[title]} for n in notes) mcp.tool() def notes_search(keyword: str) - str: Search notes by keyword in title or content. kw keyword.strip().lower() if not kw: return Error: keyword cannot be empty. hits [n for n in _load() if kw in n[title].lower() or kw in n[content].lower()] if not hits: return fNo notes matching {keyword}. return \n\n.join(f#{n[id]} {n[title]}\n{n[content]} for n in hits) if __name__ __main__: mcp.run(transportstdio)對(duì)照 mcp-builder 的規(guī)范這段代碼有幾個(gè)刻意的設(shè)計(jì)點(diǎn)值得說(shuō)。Tool 名用notes_前綴加動(dòng)作Agent 在發(fā)現(xiàn)工具時(shí)更容易歸類docstring 里明確寫(xiě)了每個(gè)參數(shù)的含義Claude 靠它填參寫(xiě)含糊了它就會(huì)瞎猜錯(cuò)誤返回的是可行動(dòng)文案Provide a title and retry而不是拋未捕獲異常這樣 Agent 能自己糾正只讀 toolnotes_list、notes_search不寫(xiě)盤(pán)寫(xiě)盤(pán) toolnotes_add邊界清晰。Transport 選型上個(gè)人本地工具用 stdio 就夠了。如果你要團(tuán)隊(duì)遠(yuǎn)程共享才需要換成 streamable HTTP那是進(jìn)階場(chǎng)景本篇先不展開(kāi)。本地先驗(yàn)證一下能不能起來(lái)python server.py如果掛起沒(méi)有報(bào)錯(cuò)說(shuō)明 Server 正常啟動(dòng)按 CtrlC 退出。這一步只是確認(rèn)進(jìn)程能跑真正的功能驗(yàn)證交給下一節(jié)的 Inspector。接入 Claude Code 有兩種方式先給命令行方式個(gè)人 scope推薦先試claude mcp add --transport stdio pocket-notes -- python /絕對(duì)路徑/pocket-notes-mcp/server.pyWindows 示例claude mcp add --transport stdio pocket-notes -- python E:\pocket-notes-mcp\server.py再給項(xiàng)目級(jí)配置方式適合團(tuán)隊(duì)共享、可以提交 Git。在項(xiàng)目根目錄建.mcp.json{ mcpServers: { pocket-notes: { type: stdio, command: python, args: [E:/tools/pocket-notes-mcp/server.py] } } }注意 args 里的路徑用正斜杠Windows 下反斜杠在 JSON 里要轉(zhuǎn)義容易出錯(cuò)。項(xiàng)目級(jí)配置首次加載時(shí) Claude Code 可能會(huì)彈交互讓你批準(zhǔn)這是正常的安全機(jī)制。4. 驗(yàn)證請(qǐng)求MCP Inspector 調(diào)試與對(duì)話驗(yàn)收代碼寫(xiě)完不等于能用。接入 Claude 之前先用官方 MCP Inspector 單獨(dú)測(cè) tool把 Server 邏輯和 Claude 的調(diào)用行為分開(kāi)驗(yàn)證這樣出問(wèn)題時(shí)你能快速定位是 Server 的鍋還是配置的鍋。啟動(dòng) Inspectornpx modelcontextprotocol/inspector python server.py它會(huì)啟動(dòng)一個(gè)本地服務(wù)并打印一個(gè)瀏覽器地址打開(kāi)后你會(huì)看到 Inspector 界面左側(cè)列出你的三個(gè) tool。按順序測(cè)三步第一步調(diào) notes_add參數(shù) title購(gòu)物清單content牛奶、雞蛋。預(yù)期返回Added note #1: 購(gòu)物清單。第二步調(diào) notes_list預(yù)期返回#1 購(gòu)物清單。第三步調(diào) notes_search參數(shù) keyword牛奶預(yù)期返回完整條目包含標(biāo)題和內(nèi)容。三步全過(guò)說(shuō)明 Server 邏輯正確可以接入 Claude Code 了。如果某一步失敗先看 Inspector 里的錯(cuò)誤信息再對(duì)照下一節(jié)的排查表。接入后完全重啟 Claude Code輸入/mcp你應(yīng)該能看到 pocket-notes 以及它下面的 3 個(gè) tool。如果沒(méi)看到先claude mcp list查狀態(tài)。然后是對(duì)話驗(yàn)收在 Claude Code 里依次說(shuō)三句話第一句用 pocket-notes 添加筆記標(biāo)題「學(xué)習(xí)計(jì)劃」內(nèi)容「本周完成 MCP 教程」。第二句列出我所有筆記。第三句搜索包含 MCP 的筆記。成功標(biāo)志有兩個(gè)一是 Claude 實(shí)際調(diào)用了 MCP tool你會(huì)在對(duì)話里看到工具調(diào)用記錄二是打開(kāi)~/.pocket-notes/notes.jsonWindows 是C:\Users\你的用戶名\.pocket-notes\notes.json內(nèi)容與對(duì)話一致。這里補(bǔ)一句關(guān)于 Eval 的思路。mcp-builder 的 Phase 4 強(qiáng)調(diào)設(shè)計(jì) Eval 驗(yàn)證 Agent 能否真正用好你的 Server。最簡(jiǎn)單的 Eval 就是上面這三句話如果 Claude 能正確選 tool、正確填參、正確解讀返回說(shuō)明你的 docstring 和 tool 設(shè)計(jì)到位了。如果它選錯(cuò) tool 或者參數(shù)填錯(cuò)回去改 docstring而不是改代碼邏輯。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed 與 reading choices這一節(jié)對(duì)照真實(shí)報(bào)錯(cuò)把最容易踩的坑列出來(lái)。注意本篇的本地 stdio Server 本身不涉及遠(yuǎn)程鑒權(quán)所以 401 這類錯(cuò)誤通常出現(xiàn)在你后續(xù)接遠(yuǎn)程模型或 HTTP transport 的場(chǎng)景這里一并說(shuō)清。先看 Inspector 連不上的情況。最常見(jiàn)原因是路徑問(wèn)題python server.py用的是相對(duì)路徑但 Inspector 啟動(dòng)時(shí)工作目錄可能變了。解決辦法是統(tǒng)一用絕對(duì)路徑npx modelcontextprotocol/inspector python /絕對(duì)路徑/server.py。第二個(gè)原因是環(huán)境不一致pip install mcp 裝的環(huán)境和運(yùn)行 server.py 的 python 不是同一個(gè)回到第 2 節(jié)用 venv 統(tǒng)一。再看/mcp里看不到 Server。先跑claude mcp list查狀態(tài)如果顯示未連接重啟 Claude Code。項(xiàng)目級(jí).mcp.json首次加載需要交互批準(zhǔn)如果你跳過(guò)了批準(zhǔn)Server 不會(huì)生效。另外檢查 JSON 語(yǔ)法多一個(gè)逗號(hào)都會(huì)導(dǎo)致整個(gè)配置解析失敗。Tool 調(diào)用失敗時(shí)看終端里的 MCP 日志。FastMCP 會(huì)把異常打到 stderr如果日志里出現(xiàn)ModuleNotFoundError還是環(huán)境問(wèn)題如果出現(xiàn)文件權(quán)限錯(cuò)誤檢查~/.pocket-notes/目錄是否可寫(xiě)。關(guān)于 401 和 local proxy failed這兩個(gè)報(bào)錯(cuò)一般出現(xiàn)在你把 Server 接到遠(yuǎn)程模型網(wǎng)關(guān)做 Eval 的時(shí)候。401 是 Key 無(wú)效或過(guò)期去 https://taotoken.net/api-keys 重新生成local proxy failed 通常是本地網(wǎng)絡(luò)配置或 Base URL 寫(xiě)錯(cuò)確認(rèn)你填的是 https://taotoken.net/api 而不是別的地址。如果你在 Claude Code 里配了遠(yuǎn)程模型檢查 settings 里的 Base URL、Key、Model ID 三件套是否齊全缺一個(gè)都會(huì)失敗。關(guān)于reading choices報(bào)錯(cuò)這通常出現(xiàn)在調(diào)用遠(yuǎn)程模型返回體解析時(shí)說(shuō)明返回結(jié)構(gòu)和你預(yù)期的不一致多半是 Base URL 指向了錯(cuò)誤的端點(diǎn)或者 Model ID 填了一個(gè)不存在的模型。對(duì)照接入文檔 https://taotoken.net/doc 確認(rèn)端點(diǎn)格式。關(guān)于 OAuth 報(bào)錯(cuò)如果你用的是需要 OAuth 的遠(yuǎn)程 MCP Servertoken 過(guò)期會(huì)報(bào)這個(gè)。本地 stdio Server 不涉及但如果你在 Cline MCP 或 Codex 的 auth.json 里配了遠(yuǎn)程 Server檢查 token 是否刷新。想換 TypeScript 實(shí)現(xiàn)的話mcp-builder Skill 里有 node_mcp_server.md適合做遠(yuǎn)程 HTTP Server。Python 版適合本地快速驗(yàn)證TypeScript 版適合團(tuán)隊(duì)共享和部署?，F(xiàn)象處理Inspector 連不上用絕對(duì)路徑確認(rèn) python 和 pip install mcp 在同一環(huán)境/mcp 無(wú) Server重啟 Claudeclaude mcp list 查狀態(tài)檢查 .mcp.json 語(yǔ)法Tool 調(diào)用失敗看終端 MCP 日志確認(rèn) venv 路徑一致401Key 無(wú)效去 api-keys 重新生成local proxy failed檢查 Base URL 是否為 https://taotoken.net/apireading choices端點(diǎn)或 Model ID 錯(cuò)誤對(duì)照接入文檔OAuth 報(bào)錯(cuò)遠(yuǎn)程 Server token 過(guò)期刷新 token想換 TypeScript看 Skill 內(nèi) node_mcp_server.md6. 把 Server 接到長(zhǎng)期編碼流Coding Plan 與后續(xù)擴(kuò)展跑通第一個(gè) Server 之后你大概率會(huì)想把它接到日常編碼流里讓 Claude 在寫(xiě)代碼時(shí)順手調(diào)用你的內(nèi)部工具。這時(shí)候有幾個(gè)方向可以擴(kuò)展。第一個(gè)方向是把 stdio 換成 streamable HTTP讓團(tuán)隊(duì)共享。stdio 是單機(jī)進(jìn)程每個(gè)人都要本地裝一份HTTP transport 可以部署到內(nèi)網(wǎng)團(tuán)隊(duì)成員通過(guò) URL 接入。mcp-builder 的 Skill 里有對(duì)應(yīng)的指引TypeScript 版更適合這個(gè)場(chǎng)景。第二個(gè)方向是擴(kuò)充 tool 覆蓋范圍。pocket-notes 只有三個(gè) tool真實(shí)內(nèi)部系統(tǒng)往往需要十幾個(gè)。mcp-builder 的 Phase 1 規(guī)劃方法在這里很關(guān)鍵先列出所有 API 端點(diǎn)再?zèng)Q定哪些暴露成 tool、怎么命名、怎么分組。不要一股腦全暴露Agent 面對(duì)太多 tool 會(huì)選錯(cuò)。第三個(gè)方向是接遠(yuǎn)程模型做 Eval。本地 stdio 不需要遠(yuǎn)程模型但如果你想批量測(cè)試 Agent 在不同模型下的 tool 調(diào)用準(zhǔn)確率就需要一個(gè)穩(wěn)定的模型網(wǎng)關(guān)。這時(shí)候 TaoToken 的 Coding Plan 比較合適適合長(zhǎng)期編碼和 Agent 場(chǎng)景地址在 https://taotoken.net/coding-plan 。模型對(duì)話調(diào)試可以用 https://taotoken.net/models 控制臺(tái)在 https://taotoken.net/console 。如果你用的是 Claude Code 的 Anthropic 兼容接入配置片段大致是這樣注意 Base URL、Key、Model ID 三件套要齊全{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的Key, ANTHROPIC_MODEL: 你的ModelID } }Claude Code 的 Anthropic 接入文檔在 https://taotoken.net/claudecode-anthropic 里面有完整的 settings 示例。Cline MCP 和 Codex 的 auth.json 配置同理都是 Base URL 加 Key 加 Model ID缺一不可。最后說(shuō)一個(gè)真實(shí)經(jīng)驗(yàn)MCP Server 的調(diào)試成本八成花在 docstring 和錯(cuò)誤文案上而不是業(yè)務(wù)邏輯。業(yè)務(wù)邏輯你寫(xiě)十行就完了但讓 Agent 正確選 tool、正確填參、正確解讀返回需要反復(fù)打磨 docstring。mcp-builder 的價(jià)值就在這——它把 MCP 工程規(guī)范沉淀成了可復(fù)用的方法你照著走能少踩很多坑。80 行 Python 走完編寫(xiě)、Inspector、Claude Code 全鏈路這就是你的第一個(gè) MCP Server。