1. 从零写一个 MCP Server为什么卡在“本地工具链”这一步MCP Server 说白了就是给大模型装一个“本地工具箱”模型本身只会聊天但通过 MCP 协议它可以调用你写的函数去查天气、读文件、查数据库、跑脚本。你写一个 Server暴露几个 tool然后在 Cline、Claude for Desktop、CC Switch 这类客户端里注册模型就能在对话里主动调用它们。听起来很顺但真正动手的人大多会卡在同一个地方——本地联调。我见过太多人 Server 代码写完了uv run weather.py也能跑结果一接客户端就报“server not found”或者工具列表是空的。问题往往不在 MCP 协议本身而在两件事一是客户端配置里的路径、命令、参数没对齐二是每个客户端都要单独配一份 Key 和 endpoint工具一多配置文件就变成一团乱麻。这篇就围绕“从零开发到本地联调”这条完整路径来讲重点交付三样东西可复制的settings.json与config.toml骨架、统一 Key 的配置片段、以及启动后验证工具调用是否生效的具体命令和排查步骤。适合谁看已经会写 Python 或 Node想在 Cline、CC Switch 里接入自建 MCP 服务的开发者或者手上已经有几个 MCP Server但被多份 Key、多份配置折磨得想统一管理的人。下面我用一个天气 Server 做例子因为它足够小能让你把注意力放在“联调”而不是业务逻辑上。整个流程走完你手里会有一个能跑通的 Server、一份能直接抄的客户端配置以及一套出问题时的排查顺序。2. 前置准备统一 Key 与 MCP 依赖环境在写 Server 之前先把两件事定下来运行环境和 Key 管理方式。环境这块Python 3.10 是硬要求MCP SDK 建议 1.2.0 以上。我习惯用 uv 管理虚拟环境和依赖比 pip 干净启动也快。Key 这块如果你只接一个客户端、一个模型随便填也行但 MCP 的典型场景是“一个 Server 被多个客户端调用”Cline 要一份、CC Switch 要一份、脚本里可能还要一份这时候统一 Key 就很有必要。统一 Key 的思路是所有客户端和本地脚本都指向同一个 API 地址、用同一把 Key换模型或换额度时只改一处。TaoToken 的接入地址是https://taotoken.net/api控制台在https://taotoken.net/consoleKey 在https://taotoken.net/api-keys生成。你先把 Key 拿到手后面配置里会反复用到。注意别把 Key 硬编码进 Server 源码用环境变量或者客户端配置里的env字段传进去这样提交代码时不会泄露。环境初始化命令如下Linux/macOS 通用# 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 重开终端后验证 uv --version # 建项目 uv init weather-mcp cd weather-mcp uv venv source .venv/bin/activate # 装依赖mcp[cli] 带命令行调试工具 uv add mcp[cli] httpx touch weather.pyWindows 用户把source .venv/bin/activate换成.venv\Scripts\activate即可。装完确认一下uv run python -c import mcp; print(mcp.__version__)能打印版本号低于 1.2.0 就uv add mcp[cli]1.2.0升一下。这一步别省SDK 版本不对后面mcp.tool()装饰器行为会有差异。3. 可复制配置Server 骨架与客户端 settings.json / config.toml3.1 写一个最小可用的 MCP Server先给一份能直接跑的weather.py暴露两个工具get_alerts和get_forecast。核心是用FastMCP类它靠类型提示和 docstring 自动生成工具定义省掉手写 schema 的麻烦。from typing import Any import httpx from mcp.server.fastmcp import FastMCP mcp FastMCP(weather) NWS_API_BASE https://api.weather.gov USER_AGENT weather-mcp/1.0 async def make_nws_request(url: str) - dict[str, Any] | None: headers {User-Agent: USER_AGENT, Accept: application/geojson} async with httpx.AsyncClient() as client: try: resp await client.get(url, headersheaders, timeout30.0) resp.raise_for_status() return resp.json() except Exception: return None mcp.tool() async def get_alerts(state: str) - str: 获取美国某州的天气警报。 参数: state: 两个字母的州代码例如 CA、NY url f{NWS_API_BASE}/alerts/active/area/{state} data await make_nws_request(url) if not data or features not in data: return 无法获取警报数据。 if not data[features]: return 该州当前没有活跃警报。 return \n---\n.join( fEvent: {f[properties].get(event)}\nArea: {f[properties].get(areaDesc)} for f in data[features] ) mcp.tool() async def get_forecast(latitude: float, longitude: float) - str: 获取指定经纬度的天气预报。 参数: latitude: 纬度 longitude: 经度 points await make_nws_request(f{NWS_API_BASE}/points/{latitude},{longitude}) if not points: return 无法获取网格点数据。 forecast await make_nws_request(points[properties][forecast]) if not forecast: return 无法获取详细预报。 periods forecast[properties][periods][:5] return \n---\n.join( f{p[name]}: {p[temperature]}°{p[temperatureUnit]}, f风 {p[windSpeed]} {p[windDirection]}\n{p[detailedForecast]} for p in periods ) if __name__ __main__: mcp.run(transportstdio)transportstdio是关键本地客户端基本都是通过标准输入输出跟 Server 通信的。跑一下uv run weather.py如果没报错、进程挂起等待输入说明 Server 本身没问题。3.2 Cline 的 settings.json 骨架Cline 是 VS Code 插件配置走settings.json。在 VS Code 里按CtrlShiftP搜 “Preferences: Open User Settings (JSON)”把下面这段加进去。注意command用uv的绝对路径--directory指向项目根目录别用相对路径。{ cline.mcpServers: { weather: { command: /Users/yourname/.local/bin/uv, args: [ --directory, /Users/yourname/projects/weather-mcp, run, weather.py ], env: { TAOTOKEN_API_KEY: sk-你的统一Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }which uv拿到绝对路径填进command。env里塞统一 KeyServer 代码里用os.environ.get(TAOTOKEN_API_KEY)读这样换 Key 只改这一处。3.3 CC Switch 的 config.toml 骨架CC Switch 用 TOML 配置结构类似但字段名不同。在它的配置目录下建config.toml[[mcp_servers]] name weather command /Users/yourname/.local/bin/uv args [--directory, /Users/yourname/projects/weather-mcp, run, weather.py] [mcp_servers.env] TAOTOKEN_API_KEY sk-你的统一Key TAOTOKEN_BASE_URL https://taotoken.net/api两份配置的差异主要在字段命名JSON 用mcpServers对象TOML 用[[mcp_servers]]数组。参数结构基本一致抄的时候注意别把 JSON 的冒号带进 TOML。4. 验证请求确认工具调用真的生效配置写完重启客户端接下来是验证。分三层Server 层、协议层、客户端层。第一层Server 能不能独立跑。用 MCP 自带的 CLI 调试工具不用开客户端就能看工具列表uv run mcp dev weather.py它会启动一个本地调试界面列出get_alerts和get_forecast两个工具还能手动传参调用。如果这里看不到工具说明装饰器或类型提示有问题先修 Server 再谈客户端。第二层协议层握手。用mcpCLI 直接发 JSON-RPC 请求echo {jsonrpc:2.0,id:1,method:tools/list,params:{}} | uv run weather.py正常会返回一个包含两个工具定义的 JSON。如果返回空或者报错检查mcp.run(transportstdio)有没有写对。第三层客户端层。在 Cline 或 CC Switch 里打开对话问一句“加州现在有哪些天气警报”。模型应该会主动调用get_alerts你能在工具调用面板看到入参{state: CA}和返回结果。如果模型只是用自然语言回答、没触发工具说明工具没注册成功回到第一层查。验证统一 Key 是否生效可以在 Server 里加一个调用 TaoToken 的测试工具或者直接在客户端里问一个需要走 API 的问题看请求有没有正常返回。Key 不对的典型表现是 401日志里能看到。5. 本篇常见错排查工具列表为空。九成是路径问题。--directory必须是绝对路径command必须是uv的绝对路径。用which uv确认别想当然写uv。另外确认weather.py在--directory指向的目录下。Server 启动即退出。多半是依赖没装进虚拟环境。uv run会自动用项目虚拟环境但如果你在别的目录跑可能用了全局 Python。统一在项目根目录执行uv run weather.py。客户端报 “server not found”。JSON 语法错误最常见逗号、引号、括号对不上。用python -m json.tool settings.json校验一下。TOML 用python -c import tomllib; tomllib.load(open(config.toml,rb))校验。工具调用静默失败。客户端日志是关键。Cline 的日志在 VS Code 输出面板选 “Cline” 频道Claude for Desktop 的日志在~/Library/Logs/Claude/mcp*.log用tail -n 20 -f ~/Library/Logs/Claude/mcp*.log实时看。日志里会打印 Server 的 stderr报错信息基本都在那。401 或鉴权失败。检查env里的 Key 有没有拼错TAOTOKEN_BASE_URL是不是https://taotoken.net/api。Key 在https://taotoken.net/api-keys重新生成一份对比测试。改了配置不生效。客户端要完全重启不是关窗口是退出进程再开。VS Code 里 Cline 改配置后建议 reload window。6. 把统一 Key 接进你的日常工具链Server 跑通之后统一 Key 的价值才真正体现出来。你可以在weather.py里加一个走 TaoToken 的工具比如让模型总结天气警报这样 Server 本身就依赖统一 Keyimport os from openai import AsyncOpenAI client AsyncOpenAI( api_keyos.environ.get(TAOTOKEN_API_KEY), base_urlos.environ.get(TAOTOKEN_BASE_URL), ) mcp.tool() async def summarize_alerts(state: str) - str: 用模型总结某州的天气警报。 raw await get_alerts(state) resp await client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: f总结这些警报\n{raw}}], ) return resp.choices[0].message.content这样 Cline、CC Switch、脚本全都共用同一把 Key换模型只改model字段。如果你长期在编码场景里用 MCP比如让 Agent 自动调工具改代码可以看看 Coding Plan 的额度方案比按次调用划算。模型对话调试在https://taotoken.net/models接入文档在https://taotoken.net/docKey 管理在https://taotoken.net/api-keys。配置骨架和排查顺序都在上面了剩下的就是把你自己的业务函数塞进mcp.tool()里跑一遍mcp dev确认工具列表再重启客户端验证调用。