摘要本文面向想入门 MCPModel Context Protocol的开发者用 30 分钟从零实现一个可运行的 MCP Server并接入 Claude Desktop 完成调用。包含完整 Python 代码、配置文件和 5 个高频报错的解决方法亲测有效。标签AI、Agent、MCP、大模型、AI编程前言为什么 MCP 突然就火了2026 年做 AI 应用开发绕不开两个协议一个是模型之间的通信另一个就是模型和工具之间的连接——后者就是 MCPModel Context Protocol。简单说MCP 是 Anthropic 在 2024 年底开源的一个协议标准用来解决一个老大难问题**每个 AI 应用接每个工具都要单独写一遍适配代码**。飞书要写一遍、GitHub 要写一遍、数据库又要写一遍换一个 AI 客户端全部重来。MCP 的思路是把这些工具能力标准化成一个个独立的 Server任何支持 MCP 的客户端Claude Desktop、Cursor、各种自研 Agent都能即插即用。写一次处处运行。一、30 秒理解 MCP 的三个核心概念MCP 的架构一共三个角色用一句话各概括一个Host宿主AI 应用本身比如 Claude Desktop、Cursor。它负责跑模型、管理对话。Client客户端Host 内部维护的连接器每个 MCP Server 对应一个 Client 实例一对一通信。Server服务端真正干活的进程对外暴露三种能力——Tools工具可被模型主动调用、Resources资源可被读取的数据、Prompts提示词模板。理解成本最高的其实是Tool和Resource的区别。我的经验是这样记Tool 是模型决定要做的动作如发消息、查数据库Resource 是模型随时可读的数据如文件、配置。90% 的场景你只需要写 Tool。MCP 底层传输支持两种方式stdio本地子进程最常用和 Streamable HTTP远程服务。本地教程用 stdio 就够了。二、环境准备2 分钟只需要 Python 3.10然后装官方 SDK# 建议先创建虚拟环境 python -m venv mcp-demo # Windows 激活 mcp-demo\Scripts\activate # macOS / Linux 激活 source mcp-demo/bin/activate # 安装官方 Python SDKfastmcp 已并入官方包 pip install mcp[cli]装完检查版本确认在 1.x 以上mcp version三、写一个最小可用的 MCP Server10 分钟我们来实现一个天气查询 计算器的玩具 Server麻雀虽小五脏俱全。新建 server.pyfrom mcp.server.fastmcp import FastMCP import httpx # 创建 MCP 服务实例 mcp FastMCP(demo-tools) mcp.tool() async def get_weather(city: str) - str: 查询指定城市的实时天气示例用 wttr.in 免费接口 url fhttps://wttr.in/{city}?formatj1 async with httpx.AsyncClient(timeout10) as client: resp await client.get(url) data resp.json() current data[current_condition][0] return f{city} 当前温度 {current[temp_C]}°C天气 {current[weatherDesc][0][value]} mcp.tool() def add(a: float, b: float) - float: 两数相加 return a b mcp.resource(config://app) def get_config() - str: 应用配置信息 return demo-tools v1.0, author: dev if __name__ __main__: mcp.run() # 默认 stdio 模式几个关键点说明1. mcp.tool() 装饰器会自动把函数注册为工具函数的 docstring 就是模型看到的工具说明一定要写清楚模型靠它决定什么时候调用2. 参数类型注解会自动转成 JSON Schema模型传参会严格遵守3. mcp.run() 默认走 stdio调试时可以换成 mcp.run(transportsse) 配合浏览器看日志。在本地验证一下 Server 能不能启动mcp dev server.py这条命令会启动官方 Inspector 调试界面你可以在浏览器里直接看到工具列表、手动调用测试这一步强烈建议做能提前暴露 80% 的问题。四、接入 Claude Desktop10 分钟编辑 Claude Desktop 的配置文件没有就新建macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.json{ mcpServers: { demo-tools: { command: python, args: [ C:/projects/mcp-demo/server.py ] } } }注意两点command 必须是能直接在终端跑通的命令虚拟环境要写全路径路径用正斜杠或双反斜杠。保存后完全退出Claude Desktop托盘图标也要退出再重新打开在对话框左下角的工具图标里就能看到 get_weather 和 add 两个工具。直接问它北京今天多少度它会先请求调用权限确认后返回结果。五、5 个高频报错与解决方法亲测有效ModuleNotFoundError: No module named mcpServer 进程用了错误的 Python。解决配置里 command 改成虚拟环境的绝对路径如 C:/projects/mcp-demo/Scripts/python.exe。连接成功但工具列表为空函数没被装饰器注册或者 docstring 缺失。每个 mcp.tool() 函数必须有 docstring。Claude Desktop重启后仍看不到 Server**JSON 格式错误多了逗号或路径反斜杠没转义用 Inspector 先验证 JSON。Error: spawn ENOENTcommand 写了 python3 但 Windows 下不存在改成 python 或写绝对路径。异步工具超时httpx 默认没有超时控制遇到慢接口会挂起整个 Server务必像上文一样显式传 timeout10。写在最后MCP 本身的上手成本并不高真正的工作量在把业务能力抽象成粒度合适的 Tool一个工具做一件事、参数尽量少、返回结构化文本。建议从自己工作里最重复的那个动作开始写第一个 Server——比如自动查日志、自动发周报写完你会回来感谢这篇文章的。如果搭建过程中遇到别的报错欢迎在评论区贴出来我看到会回复。声明本文所有代码均为原创实测转载请注明出处。