1. 从 weather.py 到 Claude CodeMCP 落地的真实卡点如果你已经看过 Claude Code 官方最佳实践里关于 MCP 的那一节大概会有一种“道理都懂但手就是动不起来”的感觉。官方文档告诉你 MCP 是模型上下文协议能让 Claude Code 调用外部工具也告诉你用 FastMCP 可以快速写一个服务端。但真正落到键盘上问题就来了weather.py 到底怎么写才不会被 Claude Code 拒收settings.json 和 config.toml 里那些字段哪个是必须的启动之后怎么确认工具真的被注册进去了为什么控制台一片安静日志去哪了这篇就是来解决这些“最后一公里”的问题。我会用一个最小可跑的 weather.py 作为例子把 FastMCP 服务端骨架、Claude Code 的接入配置、TaoToken 统一 Key 通道的接法以及验证工具调用链路的完整动作串起来。适合已经装好 Claude Code、想跑通第一个自定义 MCP 工具的人。读完你手里会有一个能查天气的 MCP 服务并且知道每一步为什么这么配。需要先说明一点MCP 的 stdio 模式对输出极其敏感。服务端往 stdout 里多打一行字Claude Code 那边就可能直接报 JSON 解析错误。这个坑我在后面会专门拆开讲因为它几乎是新手必踩的第一个雷。2. TaoToken 前置把 Key 和 API 通道先理顺在写 weather.py 之前建议先把模型侧的通道配好。原因很简单Claude Code 本身要通过一个 API 端点来调用模型而 MCP 工具调用是挂在这条链路之上的。如果模型通道本身没通你后面验证 MCP 的时候会分不清是工具没注册还是模型根本没响应。TaoToken 在这里的角色是提供一个统一的 Key 和 API 入口。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解它的定位实际接入时用的是 API 地址 https://taotoken.net/api这个不加 UTM。拿到 Key 之后Claude Code 的模型请求就走这条通道。具体操作上先去控制台创建一个 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面生成一个 Key复制保存。这个 Key 后面会写进 Claude Code 的配置里。如果你还没决定用哪种接入方式可以先在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试一下模型是否正常响应。确认通道没问题再往下走 MCP 的部分排障会轻松很多。对于长期在 Claude Code 里做编码和 Agent 任务的场景Coding Plan 会更合适入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它的额度模型对高频调用更友好MCP 工具反复触发也不会心疼。3. 可复制配置weather.py 骨架与 Claude Code 接入3.1 写一个最小可用的 weather.py先建目录再建文件。假设你的项目目录叫 weather-mcpmkdir weather-mcp cd weather-mcp然后创建 weather.py。这里我用一个公开的天气接口做示例你只需要替换成自己的 Key 即可。注意代码里没有任何 print 语句这是刻意的。import os import httpx from mcp.server.fastmcp import FastMCP # 替换为你自己的天气 API Key WEATHER_KEY os.environ.get(WEATHER_KEY, 你的_API_KEY) mcp FastMCP(WeatherServer) mcp.tool() async def get_weather(city: str) - str: 查询指定城市的实时天气。 Args: city: 城市名称例如 宁波、北京 url https://restapi.amap.com/v3/weather/weatherInfo params { key: WEATHER_KEY, city: city, extensions: base, } async with httpx.AsyncClient() as client: resp await client.get(url, paramsparams) data resp.json() if data.get(status) 1 and data.get(lives): live data[lives][0] return ( f城市{live[province]}{live[city]}\n f天气{live[weather]}\n f温度{live[temperature]}°C\n f风向{live[winddirection]}风 {live[windpower]}级\n f湿度{live[humidity]}%\n f发布时间{live[reporttime]} ) return f查询失败{data.get(info, 请检查城市名或 Key)} if __name__ __main__: mcp.run()依赖安装建议用虚拟环境避免污染全局 Pythonpython3 -m venv .venv source .venv/bin/activate pip install httpx fastmcp[all]装完之后先单独跑一下服务端确认它能启动python weather.py如果它安静地停在那里不报错说明 stdio 服务端已经就绪。这时候按 CtrlC 退出准备接入 Claude Code。3.2 配置 Claude Code 的 MCP 接入Claude Code 读取 MCP 配置的位置通常在项目根目录的.mcp.json或者用户级的 settings 里。推荐用项目级.mcp.json隔离性好换项目不会互相干扰。在项目根目录创建.mcp.json{ mcpServers: { weather: { command: /绝对路径/weather-mcp/.venv/bin/python, args: [ /绝对路径/weather-mcp/weather.py ], env: { WEATHER_KEY: 你的_API_KEY } } } }这里有两个关键点。第一command 必须指向虚拟环境里的 python而不是系统 python否则依赖找不到。第二路径必须是绝对路径相对路径在 Claude Code 启动时的工作目录下容易解析失败。如果你用的是 config.toml 形式的配置部分版本支持骨架类似[mcp_servers.weather] command /绝对路径/weather-mcp/.venv/bin/python args [/绝对路径/weather-mcp/weather.py] [mcp_servers.weather.env] WEATHER_KEY 你的_API_KEY配置写完后重启 Claude Code或者新开一个对话让它重新加载 MCP 配置。3.3 把模型通道指向 TaoTokenMCP 工具要能被调用前提是 Claude Code 的模型请求是通的。在 Claude Code 的配置里把 API 端点指向 TaoTokenexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的_TaoToken_Key如果你用的是 settings.json 形式可以写成{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的_TaoToken_Key } }这样模型请求走 TaoToken 通道MCP 工具调用挂在同一条链路上排障时只需要看一个方向。4. 验证请求确认工具真的被注册和调用4.1 检查 MCP 是否加载成功重启 Claude Code 后先问它一句当前有哪些可用的 MCP 工具如果配置正确它应该会列出 weather 相关的工具比如get_weather。如果没列出来说明配置没被读取回到上一步检查.mcp.json的路径和 JSON 格式。4.2 触发一次真实调用直接问宁波现在的天气怎么样Claude Code 会识别到这是一个需要调用get_weather的请求然后通过 MCP 协议把city宁波传给你的 weather.py。服务端请求天气接口把结果返回给模型模型再组织成自然语言回复你。成功的话你会看到类似这样的输出城市浙江宁波 天气晴 温度28°C 风向东南风 3级 湿度65% 发布时间2024-xx-xx xx:xx:xx这一步跑通说明从 FastMCP 服务端到 Claude Code 工具调用的整条链路是通的。4.3 看日志的正确姿势很多人会问为什么 VSCode 控制台没有打印日志因为 MCP 的 stdio 模式要求服务端只能输出标准 JSON 通信数据。你在代码里加一个print(debug)Claude Code 那边就会读到非 JSON 内容直接报Invalid JSON: expected value at line 1 column 2。正确的日志做法是写到文件或者用 stderrimport sys print(debug info, filesys.stderr)stderr 不会被 MCP 协议解析所以安全。stdout 留给协议本身。5. 本篇常见错排查5.1 Invalid JSON 报错报错长这样Invalid JSON: expected value at line 1 column 2 input_valuesource ...原因通常是启动命令里混入了 shell 输出。比如你在.mcp.json的 command 里写了source .venv/bin/activate python weather.py这个source命令的输出会被 MCP 当成协议数据读进去直接崩。解决方法是不要在 command 里做激活动作直接把 command 指向虚拟环境的 python 绝对路径command: /绝对路径/weather-mcp/.venv/bin/python5.2 pip 安装报 externally-managed-environment在 macOS 上用 Homebrew 装的 Python 3.11直接pip install会报 PEP 668 保护错误。不要用--break-system-packages硬装会污染全局环境。正确做法是建虚拟环境python3 -m venv .venv source .venv/bin/activate pip install httpx fastmcp[all]每次新开终端都要重新source .venv/bin/activate。VSCode 里按Cmd Shift P选Python: Select Interpreter挑带.venv的那个代码红线就会消失。5.3 工具列不出来如果 Claude Code 说没有可用工具按顺序检查.mcp.json是不是在项目根目录JSON 格式有没有多余逗号command 路径是不是绝对路径且文件存在python 能不能手动跑起来python weather.py。这四步过一遍基本能定位。5.4 调用返回查询失败如果工具被调用了但返回“查询失败”多半是 API Key 没传进去。检查.mcp.json的env字段有没有写对或者代码里os.environ.get(WEATHER_KEY)的变量名和配置里是否一致。也可以先在终端里export WEATHER_KEYxxx再手动跑一次服务端验证。6. 继续往下走MCP 跑通之后你可以把 weather.py 当成模板复制出更多工具查快递、读数据库、调内部接口。FastMCP 的装饰器模式让新增工具的成本很低只要注意 stdout 干净、依赖装在虚拟环境里、路径用绝对路径基本不会翻车。如果你在接入过程中遇到 Key 或通道相关的问题可以直接去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 检查 Key 状态接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 有更细的字段说明。Claude Code 相关的配置细节可以参考 ClaudeCodeAnthropic 页面 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后留一个实用习惯每次改完.mcp.json先手动跑一遍python weather.py确认服务端能安静启动再重启 Claude Code。这一步能帮你过滤掉八成配置问题。
claude code（六）：【Claude Code官方最佳实践4️⃣】:MCP实战-用FastMCP写weather.py并在Claude Code接入TaoToken
1. 从 weather.py 到 Claude CodeMCP 落地的真实卡点如果你已经看过 Claude Code 官方最佳实践里关于 MCP 的那一节大概会有一种“道理都懂但手就是动不起来”的感觉。官方文档告诉你 MCP 是模型上下文协议能让 Claude Code 调用外部工具也告诉你用 FastMCP 可以快速写一个服务端。但真正落到键盘上问题就来了weather.py 到底怎么写才不会被 Claude Code 拒收settings.json 和 config.toml 里那些字段哪个是必须的启动之后怎么确认工具真的被注册进去了为什么控制台一片安静日志去哪了这篇就是来解决这些“最后一公里”的问题。我会用一个最小可跑的 weather.py 作为例子把 FastMCP 服务端骨架、Claude Code 的接入配置、TaoToken 统一 Key 通道的接法以及验证工具调用链路的完整动作串起来。适合已经装好 Claude Code、想跑通第一个自定义 MCP 工具的人。读完你手里会有一个能查天气的 MCP 服务并且知道每一步为什么这么配。需要先说明一点MCP 的 stdio 模式对输出极其敏感。服务端往 stdout 里多打一行字Claude Code 那边就可能直接报 JSON 解析错误。这个坑我在后面会专门拆开讲因为它几乎是新手必踩的第一个雷。2. TaoToken 前置把 Key 和 API 通道先理顺在写 weather.py 之前建议先把模型侧的通道配好。原因很简单Claude Code 本身要通过一个 API 端点来调用模型而 MCP 工具调用是挂在这条链路之上的。如果模型通道本身没通你后面验证 MCP 的时候会分不清是工具没注册还是模型根本没响应。TaoToken 在这里的角色是提供一个统一的 Key 和 API 入口。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解它的定位实际接入时用的是 API 地址 https://taotoken.net/api这个不加 UTM。拿到 Key 之后Claude Code 的模型请求就走这条通道。具体操作上先去控制台创建一个 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面生成一个 Key复制保存。这个 Key 后面会写进 Claude Code 的配置里。如果你还没决定用哪种接入方式可以先在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试一下模型是否正常响应。确认通道没问题再往下走 MCP 的部分排障会轻松很多。对于长期在 Claude Code 里做编码和 Agent 任务的场景Coding Plan 会更合适入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它的额度模型对高频调用更友好MCP 工具反复触发也不会心疼。3. 可复制配置weather.py 骨架与 Claude Code 接入3.1 写一个最小可用的 weather.py先建目录再建文件。假设你的项目目录叫 weather-mcpmkdir weather-mcp cd weather-mcp然后创建 weather.py。这里我用一个公开的天气接口做示例你只需要替换成自己的 Key 即可。注意代码里没有任何 print 语句这是刻意的。import os import httpx from mcp.server.fastmcp import FastMCP # 替换为你自己的天气 API Key WEATHER_KEY os.environ.get(WEATHER_KEY, 你的_API_KEY) mcp FastMCP(WeatherServer) mcp.tool() async def get_weather(city: str) - str: 查询指定城市的实时天气。 Args: city: 城市名称例如 宁波、北京 url https://restapi.amap.com/v3/weather/weatherInfo params { key: WEATHER_KEY, city: city, extensions: base, } async with httpx.AsyncClient() as client: resp await client.get(url, paramsparams) data resp.json() if data.get(status) 1 and data.get(lives): live data[lives][0] return ( f城市{live[province]}{live[city]}\n f天气{live[weather]}\n f温度{live[temperature]}°C\n f风向{live[winddirection]}风 {live[windpower]}级\n f湿度{live[humidity]}%\n f发布时间{live[reporttime]} ) return f查询失败{data.get(info, 请检查城市名或 Key)} if __name__ __main__: mcp.run()依赖安装建议用虚拟环境避免污染全局 Pythonpython3 -m venv .venv source .venv/bin/activate pip install httpx fastmcp[all]装完之后先单独跑一下服务端确认它能启动python weather.py如果它安静地停在那里不报错说明 stdio 服务端已经就绪。这时候按 CtrlC 退出准备接入 Claude Code。3.2 配置 Claude Code 的 MCP 接入Claude Code 读取 MCP 配置的位置通常在项目根目录的.mcp.json或者用户级的 settings 里。推荐用项目级.mcp.json隔离性好换项目不会互相干扰。在项目根目录创建.mcp.json{ mcpServers: { weather: { command: /绝对路径/weather-mcp/.venv/bin/python, args: [ /绝对路径/weather-mcp/weather.py ], env: { WEATHER_KEY: 你的_API_KEY } } } }这里有两个关键点。第一command 必须指向虚拟环境里的 python而不是系统 python否则依赖找不到。第二路径必须是绝对路径相对路径在 Claude Code 启动时的工作目录下容易解析失败。如果你用的是 config.toml 形式的配置部分版本支持骨架类似[mcp_servers.weather] command /绝对路径/weather-mcp/.venv/bin/python args [/绝对路径/weather-mcp/weather.py] [mcp_servers.weather.env] WEATHER_KEY 你的_API_KEY配置写完后重启 Claude Code或者新开一个对话让它重新加载 MCP 配置。3.3 把模型通道指向 TaoTokenMCP 工具要能被调用前提是 Claude Code 的模型请求是通的。在 Claude Code 的配置里把 API 端点指向 TaoTokenexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的_TaoToken_Key如果你用的是 settings.json 形式可以写成{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的_TaoToken_Key } }这样模型请求走 TaoToken 通道MCP 工具调用挂在同一条链路上排障时只需要看一个方向。4. 验证请求确认工具真的被注册和调用4.1 检查 MCP 是否加载成功重启 Claude Code 后先问它一句当前有哪些可用的 MCP 工具如果配置正确它应该会列出 weather 相关的工具比如get_weather。如果没列出来说明配置没被读取回到上一步检查.mcp.json的路径和 JSON 格式。4.2 触发一次真实调用直接问宁波现在的天气怎么样Claude Code 会识别到这是一个需要调用get_weather的请求然后通过 MCP 协议把city宁波传给你的 weather.py。服务端请求天气接口把结果返回给模型模型再组织成自然语言回复你。成功的话你会看到类似这样的输出城市浙江宁波 天气晴 温度28°C 风向东南风 3级 湿度65% 发布时间2024-xx-xx xx:xx:xx这一步跑通说明从 FastMCP 服务端到 Claude Code 工具调用的整条链路是通的。4.3 看日志的正确姿势很多人会问为什么 VSCode 控制台没有打印日志因为 MCP 的 stdio 模式要求服务端只能输出标准 JSON 通信数据。你在代码里加一个print(debug)Claude Code 那边就会读到非 JSON 内容直接报Invalid JSON: expected value at line 1 column 2。正确的日志做法是写到文件或者用 stderrimport sys print(debug info, filesys.stderr)stderr 不会被 MCP 协议解析所以安全。stdout 留给协议本身。5. 本篇常见错排查5.1 Invalid JSON 报错报错长这样Invalid JSON: expected value at line 1 column 2 input_valuesource ...原因通常是启动命令里混入了 shell 输出。比如你在.mcp.json的 command 里写了source .venv/bin/activate python weather.py这个source命令的输出会被 MCP 当成协议数据读进去直接崩。解决方法是不要在 command 里做激活动作直接把 command 指向虚拟环境的 python 绝对路径command: /绝对路径/weather-mcp/.venv/bin/python5.2 pip 安装报 externally-managed-environment在 macOS 上用 Homebrew 装的 Python 3.11直接pip install会报 PEP 668 保护错误。不要用--break-system-packages硬装会污染全局环境。正确做法是建虚拟环境python3 -m venv .venv source .venv/bin/activate pip install httpx fastmcp[all]每次新开终端都要重新source .venv/bin/activate。VSCode 里按Cmd Shift P选Python: Select Interpreter挑带.venv的那个代码红线就会消失。5.3 工具列不出来如果 Claude Code 说没有可用工具按顺序检查.mcp.json是不是在项目根目录JSON 格式有没有多余逗号command 路径是不是绝对路径且文件存在python 能不能手动跑起来python weather.py。这四步过一遍基本能定位。5.4 调用返回查询失败如果工具被调用了但返回“查询失败”多半是 API Key 没传进去。检查.mcp.json的env字段有没有写对或者代码里os.environ.get(WEATHER_KEY)的变量名和配置里是否一致。也可以先在终端里export WEATHER_KEYxxx再手动跑一次服务端验证。6. 继续往下走MCP 跑通之后你可以把 weather.py 当成模板复制出更多工具查快递、读数据库、调内部接口。FastMCP 的装饰器模式让新增工具的成本很低只要注意 stdout 干净、依赖装在虚拟环境里、路径用绝对路径基本不会翻车。如果你在接入过程中遇到 Key 或通道相关的问题可以直接去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 检查 Key 状态接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 有更细的字段说明。Claude Code 相关的配置细节可以参考 ClaudeCodeAnthropic 页面 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后留一个实用习惯每次改完.mcp.json先手动跑一遍python weather.py确认服务端能安静启动再重启 Claude Code。这一步能帮你过滤掉八成配置问题。