一、编写mcp工具并提供出来1.1 第一步获取高德地图 API 密钥 (Key)访问高德开放平台官网注册一个开发者账号。进入控制台点击“应用管理” - “我的应用” - “创建新应用”。创建好应用后点击“添加 Key”服务平台选择 Web服务。复制生成的那串 Key一串字母和数字的组合待会儿代码里要用。1.2 第二步编写天气 MCP 服务端代码在你的电脑上创建一个文件夹比如叫 weather-mcp在里面新建一个 weather.py 文件把下面的代码复制进去记得把 你的_高德_API_KEY 替换成你刚才申请的真实 Keyimportosimporthttpxfrommcp.server.fastmcpimportFastMCP# 替换为你自己的高德地图 API KeyAMAP_KEY你的_高德_API_KEYmcpFastMCP(AmapWeather)mcp.tool()asyncdefget_weather(city:str)-str: 查询指定城市的实时天气情况 Args: city: 城市名称例如宁波、北京或城市编码(adcode) # 高德天气API接口urlhttps://restapi.amap.com/v3/weather/weatherInfoparams{key:AMAP_KEY,city:city,extensions:base# base返回实况天气all返回预报天气}asyncwithhttpx.AsyncClient()asclient:respawaitclient.get(url,paramsparams)dataresp.json()ifdata.get(status)1anddata.get(lives):livedata[lives][0]return(f 城市{live[province]}{live[city]}\nf️ 天气{live[weather]}\nf️ 温度{live[temperature]}°C\nf 风向{live[winddirection]}风{live[windpower]}级\nf 湿度{live[humidity]}%\nf 发布时间{live[reporttime]})else:returnf❌ 查询失败{data.get(info,未知错误请检查城市名或API Key)}if__name____main__:mcp.run()注运行前请确保你安装了必要的依赖库可以在终端执行pip install mcp httpx1.3 第三步将天气服务接入 Claude Code代码写好后打开你的 Claude Code 终端直接对它说下面这句话把路径换成你 weather.py 所在的真实绝对路径“帮我添加一个本地 MCP 服务器名字叫 weather执行命令是 python 你的文件夹绝对路径/weather.py。”Claude Code 会自动帮你修改配置文件。配置完成后重启一下 Claude Code 或者重新开启一个对话就可以开始验收成果了你可以直接问它“宁波现在的天气怎么样”“北京今天冷不冷”二、执行步骤启动vscodemcp程序在weather_gd路径创建.mcp.json文件并设置mcpServiers你的claude目录新增.mcp.json文件这一步我不知道是不是必须的等我下次验证后再来改重启claude并询问当前mcp工具在claude code里问我的疑问为啥我vscode控制台没有打印日志三、问题与解决3.1 python环境问题基于mac环境升级python环境问题解决3.2 安装pip3 install httpx fastmcp[all]出错问题解决执行下面命令pip3installhttpxfastmcp[all]3.2.1 报错原因这个报错是 Python 3.11 版本引入的一种保护机制PEP 668。它的意思是“这是一个由外部Homebrew管理的 Python 环境为了防止把你的 Python 环境搞乱我不允许你直接用 pip 往里面强行安装包。”既然你是在做开发写.py文件最标准、最推荐的做法是使用“虚拟环境”。3.2.2 解决方法请在终端中依次运行以下三行命令创建虚拟环境在你的项目文件夹weather_gd里创建一个独立的“小环境”python3-mvenv .venv激活虚拟环境告诉终端“我现在要用这个小环境”source.venv/bin/activate行完这一步后你会看到终端提示符前面多了一个 (.venv)说明激活成功了。再次安装库现在你可以随意安装库了不会再报错pipinstallhttpxfastmcp[all]3.2.3 后续开发注意事项每次打开终端都要激活以后每次你关闭终端再重新打开或者重启电脑后如果要继续写代码都需要先运行第 2 步的激活命令source.venv/bin/activateVS Code 设置如果你用 VS Code按下Cmd Shift P打开命令面板。输入Python: Select Interpreter并回车。选择那个带有.venv字样的解释器。这样VS Code就能识别你安装的库代码里的红线也会消失。3.2.3 为什么不推荐其他方法不推荐 --break-system-packages虽然加上这个参数能强行安装但这会污染你的 Python 全局环境可能导致 Homebrew 管理的其他 Python 工具出问题。不推荐 --user这会把包安装到用户目录下虽然不报错但不利于项目管理和环境隔离。3.2 执行【1.2】的python脚步出现错误看报错信息Invalid JSON: expected value at line 1 column 2和input_valuesource ...原因非常明确MCP 服务器把虚拟环境的激活命令输出了导致 Claude 读到了非 JSON 格式的乱码。MCP 的stdio模式要求服务端只能输出标准的 JSON 通信数据任何print、source命令的输出或日志都会破坏协议。解决方法请按照以下步骤修改你的配置或启动方式新增.mcp.json配置文件文件内容如下{mcpServers:{weather:{command:/Users/qian/Document_Management/Test_Space/weather_gd/.venv/bin/python,args:[/Users/qian/Document_Management/Test_Space/weather_gd/weather.py]}}}启动vscodemcp程序重启成功。
claude code（五）：【Claude Code官方最佳实践3️⃣】:mcp实战-写一个mcp，并在claude使用
一、编写mcp工具并提供出来1.1 第一步获取高德地图 API 密钥 (Key)访问高德开放平台官网注册一个开发者账号。进入控制台点击“应用管理” - “我的应用” - “创建新应用”。创建好应用后点击“添加 Key”服务平台选择 Web服务。复制生成的那串 Key一串字母和数字的组合待会儿代码里要用。1.2 第二步编写天气 MCP 服务端代码在你的电脑上创建一个文件夹比如叫 weather-mcp在里面新建一个 weather.py 文件把下面的代码复制进去记得把 你的_高德_API_KEY 替换成你刚才申请的真实 Keyimportosimporthttpxfrommcp.server.fastmcpimportFastMCP# 替换为你自己的高德地图 API KeyAMAP_KEY你的_高德_API_KEYmcpFastMCP(AmapWeather)mcp.tool()asyncdefget_weather(city:str)-str: 查询指定城市的实时天气情况 Args: city: 城市名称例如宁波、北京或城市编码(adcode) # 高德天气API接口urlhttps://restapi.amap.com/v3/weather/weatherInfoparams{key:AMAP_KEY,city:city,extensions:base# base返回实况天气all返回预报天气}asyncwithhttpx.AsyncClient()asclient:respawaitclient.get(url,paramsparams)dataresp.json()ifdata.get(status)1anddata.get(lives):livedata[lives][0]return(f 城市{live[province]}{live[city]}\nf️ 天气{live[weather]}\nf️ 温度{live[temperature]}°C\nf 风向{live[winddirection]}风{live[windpower]}级\nf 湿度{live[humidity]}%\nf 发布时间{live[reporttime]})else:returnf❌ 查询失败{data.get(info,未知错误请检查城市名或API Key)}if__name____main__:mcp.run()注运行前请确保你安装了必要的依赖库可以在终端执行pip install mcp httpx1.3 第三步将天气服务接入 Claude Code代码写好后打开你的 Claude Code 终端直接对它说下面这句话把路径换成你 weather.py 所在的真实绝对路径“帮我添加一个本地 MCP 服务器名字叫 weather执行命令是 python 你的文件夹绝对路径/weather.py。”Claude Code 会自动帮你修改配置文件。配置完成后重启一下 Claude Code 或者重新开启一个对话就可以开始验收成果了你可以直接问它“宁波现在的天气怎么样”“北京今天冷不冷”二、执行步骤启动vscodemcp程序在weather_gd路径创建.mcp.json文件并设置mcpServiers你的claude目录新增.mcp.json文件这一步我不知道是不是必须的等我下次验证后再来改重启claude并询问当前mcp工具在claude code里问我的疑问为啥我vscode控制台没有打印日志三、问题与解决3.1 python环境问题基于mac环境升级python环境问题解决3.2 安装pip3 install httpx fastmcp[all]出错问题解决执行下面命令pip3installhttpxfastmcp[all]3.2.1 报错原因这个报错是 Python 3.11 版本引入的一种保护机制PEP 668。它的意思是“这是一个由外部Homebrew管理的 Python 环境为了防止把你的 Python 环境搞乱我不允许你直接用 pip 往里面强行安装包。”既然你是在做开发写.py文件最标准、最推荐的做法是使用“虚拟环境”。3.2.2 解决方法请在终端中依次运行以下三行命令创建虚拟环境在你的项目文件夹weather_gd里创建一个独立的“小环境”python3-mvenv .venv激活虚拟环境告诉终端“我现在要用这个小环境”source.venv/bin/activate行完这一步后你会看到终端提示符前面多了一个 (.venv)说明激活成功了。再次安装库现在你可以随意安装库了不会再报错pipinstallhttpxfastmcp[all]3.2.3 后续开发注意事项每次打开终端都要激活以后每次你关闭终端再重新打开或者重启电脑后如果要继续写代码都需要先运行第 2 步的激活命令source.venv/bin/activateVS Code 设置如果你用 VS Code按下Cmd Shift P打开命令面板。输入Python: Select Interpreter并回车。选择那个带有.venv字样的解释器。这样VS Code就能识别你安装的库代码里的红线也会消失。3.2.3 为什么不推荐其他方法不推荐 --break-system-packages虽然加上这个参数能强行安装但这会污染你的 Python 全局环境可能导致 Homebrew 管理的其他 Python 工具出问题。不推荐 --user这会把包安装到用户目录下虽然不报错但不利于项目管理和环境隔离。3.2 执行【1.2】的python脚步出现错误看报错信息Invalid JSON: expected value at line 1 column 2和input_valuesource ...原因非常明确MCP 服务器把虚拟环境的激活命令输出了导致 Claude 读到了非 JSON 格式的乱码。MCP 的stdio模式要求服务端只能输出标准的 JSON 通信数据任何print、source命令的输出或日志都会破坏协议。解决方法请按照以下步骤修改你的配置或启动方式新增.mcp.json配置文件文件内容如下{mcpServers:{weather:{command:/Users/qian/Document_Management/Test_Space/weather_gd/.venv/bin/python,args:[/Users/qian/Document_Management/Test_Space/weather_gd/weather.py]}}}启动vscodemcp程序重启成功。
