手把手教你从零搭建 MCP Server：AI 连接万物的保姆级实战教程

为什么要学 MCP说实话最近半年 AI 开发圈最火的协议就是 MCPModel Context Protocol了。你可能已经用上了各种 AI 助手但有没有想过这些 AI 怎么连接你的数据库怎么读你的本地文件怎么调用你公司的内部 API答案就是 MCP。你可以把它理解成 AI 世界的 USB-C 接口——以前每个 AI 应用对接外部系统都得写一套适配代码现在有了统一协议写一次就能到处用。Claude、ChatGPT、Cursor、VS Code Copilot 都已经支持了。我之前也觉得这东西听着高大上实际动手一搞发现真没那么难。今天就把我的经验分享出来带你从零搭一个能跑的 MCP Server。先搞清楚 MCP 的架构MCP 采用的是经典的 Client-Server 架构MCP Host就是你的 AI 应用比如 Claude Desktop、CursorMCP ClientHost 里面负责跟 Server 通信的组件MCP Server暴露工具Tools、资源Resources、提示Prompts的服务端通信方式有两种stdio通过标准输入输出通信适合本地工具SSEServer-Sent Events通过 HTTP 通信适合远程服务今天我们重点搞 stdio 方式因为上手最简单。环境准备Python 版本要求# 需要 Python 3.10python--version# Python 3.10.x 或更高安装 MCP Python SDK# 创建虚拟环境推荐python-mvenv mcp-envsourcemcp-env/bin/activate# Linux/Mac# mcp-env\Scripts\activate # Windows# 安装 MCP SDKpipinstallmcp装完之后验证一下python-cimport mcp; print(mcp.__version__)没报错就 OK。实战写一个天气查询 MCP Server我们来做一个实用的例子——让 AI 能查询城市天气。虽然是 mock 数据但整个流程是完整的你换成真实天气 API 就能用。项目结构weather-mcp-server/ ├── server.py # MCP Server 主文件 └── pyproject.toml # 项目配置可选核心代码新建server.py写入以下内容importhttpxfrommcp.server.fastmcpimportFastMCP# 创建 MCP Server 实例mcpFastMCP(weather-server)# 模拟天气数据实际项目中替换为真实 APIWEATHER_DATA{北京:{temp:22,condition:晴,humidity:35,wind:北风3级},上海:{temp:25,condition:多云,humidity:65,wind:东风2级},广州:{temp:30,condition:阵雨,humidity:80,wind:南风2级},深圳:{temp:29,condition:阴,humidity:75,wind:西南风3级},成都:{temp:20,condition:小雨,humidity:70,wind:微风},杭州:{temp:24,condition:晴转多云,humidity:55,wind:东南风2级},}mcp.tool()defget_weather(city:str)-str:查询指定城市的天气信息 Args: city: 城市名称如 北京、上海、广州 weatherWEATHER_DATA.get(city)ifweather:return(f{city}天气\nf️ 温度{weather[temp]}°C\nf️ 天气{weather[condition]}\nf 湿度{weather[humidity]}%\nf️ 风力{weather[wind]})returnf❌ 未找到城市「{city}」的天气数据目前支持{, .join(WEATHER_DATA.keys())}mcp.tool()deflist_cities()-str:列出所有可查询天气的城市citieslist(WEATHER_DATA.keys())returnf可查询的城市共{len(cities)}个{, .join(cities)}mcp.resource(weather://cities)defget_cities_resource()-str:提供城市列表作为资源return\n.join(WEATHER_DATA.keys())if__name____main__:mcp.run()就这么简单。我来逐行解释一下关键部分FastMCP(weather-server)创建 Server 实例名字随便起mcp.tool()装饰器把这个函数注册为一个 MCP 工具AI 可以调用它函数的 docstring很重要AI 靠这个理解工具的用途mcp.resource()注册一个资源AI 可以读取但不直接调用mcp.run()启动 Server默认用 stdio 方式通信运行测试python server.py启动后什么都不会输出——这是正常的因为 stdio 模式下 Server 在等 Client 发消息。配置 Claude Desktop 连接你的 Server写好 Server 只是第一步得让 AI 应用能发现它才行。找到配置文件不同系统配置文件位置不同# macOS~/Library/Application Support/Claude/claude_desktop_config.json# Windows%APPDATA%\Claude\claude_desktop_config.json# Linux如果有 Claude Desktop~/.config/Claude/claude_desktop_config.json添加 Server 配置打开配置文件加入你的 Server{mcpServers:{weather:{command:python,args:[/absolute/path/to/weather-mcp-server/server.py]}}}注意路径必须是绝对路径写相对路径会找不到。重启 Claude Desktop保存配置后重启 Claude Desktop。你会在工具栏看到一个小锤子图标 点开就能看到你注册的工具。然后直接问 Claude「北京今天天气怎么样」它就会调用你的get_weather工具返回结果。进阶用 uv 管理依赖推荐实际项目中推荐用 uv 来管理 Python 环境和依赖比 pip 好用太多# 安装 uvcurl-LsSfhttps://astral.sh/uv/install.sh|sh# 初始化项目uv init weather-mcp-servercdweather-mcp-server# 添加 MCP 依赖uvaddmcp# 运行uv run server.py对应的配置文件改成{mcpServers:{weather:{command:uv,args:[--directory,/absolute/path/to/weather-mcp-server,run,server.py]}}}常见问题 QAQ1: 启动后 Claude 没有显示工具图标大概率是配置文件路径写错了。检查JSON 格式有没有语法错误多了少了逗号server.py 的路径是不是绝对路径Python 是不是在系统 PATH 里用which python或where python检查Q2: 报错 “ModuleNotFoundError: No module named ‘mcp’”说明 Claude Desktop 启动的 Python 环境跟你安装 mcp 的环境不是同一个。解决方案用 uv 管理项目依赖推荐或者在配置里指定完整 Python 路径{command:/usr/local/bin/python3,args:[/path/to/server.py]}Q3: Server 启动了但 AI 不调用工具检查函数的 docstring 写得够不够清楚。AI 靠 docstring 理解工具用途写得越具体越好✅ “查询指定城市的天气信息包括温度、湿度、风力”❌ “查天气”Q4: 想连接真实天气 API 怎么办把 WEATHER_DATA 替换成真实的 API 调用。以和风天气为例mcp.tool()asyncdefget_weather(city:str)-str:查询城市实时天气asyncwithhttpx.AsyncClient()asclient:# 先查城市 IDgeo_respawaitclient.get(https://geoapi.qweather.com/v2/city/lookup,params{location:city,key:你的API_KEY})location_idgeo_resp.json()[location][0][id]# 再查天气weather_respawaitclient.get(https://devapi.qweather.com/v7/weather/now,params{location:location_id,key:你的API_KEY})nowweather_resp.json()[now]returnf{city}:{now[temp]}°C,{now[text]}, 湿度{now[humidity]}%Q5: 怎么调试 MCP ServerMCP 官方提供了 Inspector 工具npx modelcontextprotocol/inspector python server.py它会启动一个 Web 界面你可以手动调用工具、查看资源非常方便。完整项目代码汇总把所有代码整合到一个文件里方便复制 MCP 天气查询 Server 功能让 AI 助手能够查询城市天气信息 运行python server.py frommcp.server.fastmcpimportFastMCP# # 1. 创建 Server 实例# mcpFastMCP(weather-server,version1.0.0,description一个提供城市天气查询的 MCP Server)# # 2. 数据源可替换为真实 API# WEATHER_DB{北京:{temp:22,condition:晴,humidity:35},上海:{temp:25,condition:多云,humidity:65},广州:{temp:30,condition:阵雨,humidity:80},深圳:{temp:29,condition:阴,humidity:75},成都:{temp:20,condition:小雨,humidity:70},杭州:{temp:24,condition:晴转多云,humidity:55},武汉:{temp:26,condition:多云,humidity:60},南京:{temp:23,condition:晴,humidity:50},}# # 3. 注册工具Tools# mcp.tool()defget_weather(city:str)-str:查询指定城市的实时天气 Args: city: 城市名称中文如 北京、上海、广州 Returns: 包含温度、天气状况、湿度的格式化字符串 dataWEATHER_DB.get(city)ifnotdata:supported, .join(WEATHER_DB.keys())returnf未找到「{city}」的天气数据。支持的城市{supported}return(f{city}当前天气\nf️ 温度{data[temp]}°C\nf️ 状况{data[condition]}\nf 湿度{data[humidity]}%)mcp.tool()defcompare_weather(city1:str,city2:str)-str:对比两个城市的天气 Args: city1: 第一个城市名称 city2: 第二个城市名称 d1WEATHER_DB.get(city1)d2WEATHER_DB.get(city2)ifnotd1:returnf未找到「{city1}」的天气数据ifnotd2:returnf未找到「{city2}」的天气数据diffd1[temp]-d2[temp]warmercity1ifdiff0elsecity2return(f️ 天气对比\nf{city1}{d1[temp]}°C,{d1[condition]}\nf{city2}{d2[temp]}°C,{d2[condition]}\nf{warmer}更热温差{abs(diff)}°C)# # 4. 注册资源Resources# mcp.resource(weather://cities)deflist_all_cities()-str:返回所有可查询的城市列表return\n.join(WEATHER_DB.keys())# # 5. 注册提示Prompts# mcp.prompt()defweather_report_prompt(city:str)-str:生成天气报告的提示模板returnf请根据以下城市的天气数据生成一份简洁的天气播报适合发送给朋友\n城市{city}# # 6. 启动 Server# if__name____main__:mcp.run()总结今天我们从零搭建了一个完整的 MCP Server核心就三步装 SDKpip install mcp写代码用mcp.tool()注册工具配 Client在 Claude Desktop 配置文件里加上你的 Server整个过程其实不复杂难的是想清楚「你想让 AI 能做什么」。MCP 只是一个通道真正有价值的是你暴露给 AI 的能力。下一步你可以把 mock 数据换成真实 API天气、股票、快递查询等试试 Resources 和 Prompts 的高级用法用 SSE 模式搭建远程 MCP Server给多个 AI 应用共享同一个 ServerMCP 生态还在快速发展中早点上手绝对不亏。有问题欢迎评论区交流参考资料MCP 官方文档https://modelcontextprotocol.ioMCP Python SDKhttps://github.com/modelcontextprotocol/python-sdkMCP Server 示例合集https://github.com/modelcontextprotocol/servers