>摘要：本文面向想入门 MCP（Model Context Protocol）的开发者，用 30 分钟从零实现一个可运行的 MCP Server，并接入 Claude Desktop 完成调用。包含完整 Python 代码、配置文件和 5 个高频报错的解决方法，亲测有效。

标签：AI、Agent、MCP、大模型、AI编程

发布建议：周一早晨发布，内容等级选"初级"，配图按文中标注位置插入。

---

前言：为什么 MCP 突然就火了

2026 年做 AI 应用开发，绕不开两个协议：一个是模型之间的通信，另一个就是模型和工具之间的连接——后者就是 MCP（Model 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 SDK（fastmcp 已并入官方包）
pip install "mcp[cli]"

装完检查版本，确认在 1.x 以上：

mcp version

三、写一个最小可用的 MCP Server（10 分钟）

我们来实现一个"天气查询 + 计算器"的玩具 Server，麻雀虽小五脏俱全。新建 `server.py`：

from mcp.server.fastmcp import FastMCP
import httpx

# 创建 MCP 服务实例
mcp = FastMCP("demo-tools")

@mcp.tool()
async def get_weather(city: str) -> str:
    """查询指定城市的实时天气（示例用 wttr.in 免费接口）"""
    url = f"https://wttr.in/{city}?format=j1"
    async with httpx.AsyncClient(timeout=10) 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(transport="sse")` 配合浏览器看日志。

在本地验证一下 Server 能不能启动：

mcp dev server.py

这条命令会启动官方 Inspector 调试界面，你可以在浏览器里直接看到工具列表、手动调用测试，这一步强烈建议做，能提前暴露 80% 的问题。

四、接入 Claude Desktop（10 分钟）

编辑 Claude Desktop 的配置文件（没有就新建）：

• macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
• Windows：`%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 个高频报错与解决方法（亲测有效）

1. `ModuleNotFoundError: No module named 'mcp'`：Server 进程用了错误的 Python。解决：配置里 `command` 改成虚拟环境的绝对路径，如 `C:/projects/mcp-demo/Scripts/python.exe`。
2. 连接成功但工具列表为空：函数没被装饰器注册，或者 docstring 缺失。每个 `@mcp.tool()` 函数必须有 docstring。
3. Claude Desktop 重启后仍看不到 Server**：JSON 格式错误（多了逗号）或路径反斜杠没转义，用 Inspector 先验证 JSON。
4. `Error: spawn ENOENT`：`command` 写了 `python3` 但 Windows 下不存在，改成 `python` 或写绝对路径。
5. 异步工具超时：`httpx` 默认没有超时控制，遇到慢接口会挂起整个 Server，务必像上文一样显式传 `timeout=10`。

写在最后

MCP 本身的上手成本并不高，真正的工作量在把业务能力抽象成粒度合适的 Tool：一个工具做一件事、参数尽量少、返回结构化文本。建议从自己工作里最重复的那个动作开始写第一个 Server——比如自动查日志、自动发周报，写完你会回来感谢这篇文章的。

如果搭建过程中遇到别的报错，欢迎在评论区贴出来，我看到会回复。

声明：本文所有代码均为原创实测，转载请注明出处。