别再照抄 FastMCP 老教程了:用 MCP Python SDK v2 给 AI 写个本地工具箱
大模型最难堪的时刻,是你让它「帮我把这句话记到笔记里」——它彬彬有礼地复述了一遍,然后什么都没发生。原因很简单:模型只能输出文字,碰不到你电脑上的任何东西。MCP(Model Context Protocol)就是为解决这个问题生的:它把「AI 调用工具」这件事标准化成了一个协议,你写一个 server,任何支持 MCP 的客户端(Claude Desktop、Cursor、VS Code、各类 Agent 框架)都能直接调用你写的函数。
这个方向最近热得发烫:GitHub 上微软 2026 年 9 月还在更新的 lets-learn-mcp-python 学习仓库、B站科技区一搜一大把的 MCP 教程、知乎上的系列实践文章,都在教同一件事——用 Python 给 AI 写工具。但我在动手时踩到一个几乎所有教程都没提的坑:官方 Python SDK 已经发布 v2 稳定版,pip install mcp 现在装的就是 2.x,而网上主流教程还在教 v1 的 FastMCP 写法,照抄直接 ImportError。今天这篇就用 v2 的新写法,从零到接入真实客户端完整走一遍,全部命令和配置都按官方文档核实过。
一、先花两分钟搞懂分工:host、client、server
MCP 的世界里只有三种角色,官方文档的原话很清楚:
- host(宿主):LLM 应用本身——Claude Desktop、你的 IDE、Agent 运行时,是用户对话的那一端;
- client(客户端):住在 host 里面、说 MCP 协议的那一半,host 每连一个 server 就有一个 client;
- server(服务器):你要写的东西。它把能力暴露给 client,从不直接跟模型对话。
server 能暴露的东西也只有三种原语,区分标准是「谁决定用」:
- tools(工具):模型决定调用,比如写数据库、调 API——这是本文主角;
- resources(资源):应用决定挂载进上下文的数据,比如文件内容,类比 HTTP 的 GET;
- prompts(提示模板):用户按名字调用的消息模板,类比一条保存好的查询。
如果你写过 Web API,直觉可以直接平移:resource 是 GET(只读不加塞),tool 是 POST(真干活、有副作用),prompt 没有对应物,更像用户存的快捷指令。
二、v2 改了什么:三件事决定你抄的教程能不能跑
2026 年发布的 SDK v2 是当前稳定线,v1 进入维护模式(只收关键修复和安全补丁)。对我们写代码影响最大的三点:
FastMCP改名为MCPServer,且官方明确说旧导入路径「是被删除而不是弃用」——from mcp.server.fastmcp import FastMCP在 2.x 里直接报错,新写法是from mcp.server import MCPServer(注意:没有from mcp import MCPServer这种写法);- 传输配置搬家到
run():host、port 这类参数现在传给mcp.run()而不是构造函数,v1 的FastMCP("x", port=9000)迁过来会直接TypeError; - 协议升级到 2026-07-28 版:握手和会话被拿掉了,HTTP 请求不再绑
Mcp-Session-Id。好消息是 SDK 同一个 server 同时服务新旧两代客户端,你不用管兼容。
如果你维护的库暂时不想迁,官方建议在依赖里加上界锁死 1.x:mcp>=1.28,<2。而新项目,直接上 v2。
三、环境:一行装好,认准 Python 3.11+
SDK 对 Python 版本有硬要求:3.11 起步。装的时候带上 [cli] extra,它会多装 typer 和 python-dotenv,撑起 mcp dev / mcp run / mcp install 三个开发期命令:
# uv(推荐,文章后面所有命令都基于它)
uv add "mcp[cli]"
# 或者传统 pip
pip install "mcp[cli]"确认一下装的是哪条线:
uv pip show mcp | head -3
# Name: mcp Version: 2.x.x ...四、第一个 server:十行代码,感受一下「没写的部分」
先来官方入门文档里的最小例子,感受 v2 的写法有多省:
from mcp.server import MCPServer
mcp = MCPServer("Demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""两数相加。"""
return a + b
if __name__ == "__main__":
mcp.run()跑起来看看(mcp dev 会拉起一个叫 Inspector 的网页调试台):
uv run mcp dev server.py
# 终端会打印一个 localhost 地址,浏览器打开它Inspector 里点开 Tools 标签,你会看到 add 已经躺在列表里,还带着一张由 a: int, b: int 自动生成的表单。注意我们没有写一行 JSON Schema、没有写请求路由、没有声明能力(capabilities)——工具名来自函数名,描述来自 docstring,参数校验来自类型注解,SDK 全部自动推导。这就是这个 SDK 的核心卖点:你写的是普通 Python 函数,剩下的都是它的事。
另外两个细节值得记住:mcp.run() 不带参数时启动的是 stdio 服务器——阻塞等待,从标准输入读协议消息、往标准输出写,这是所有桌面客户端认的默认传输;它必须放在 if __name__ == "__main__": 里,因为后面接入客户端时,host 会把你的文件当模块导入而不是执行。
五、来点真的:给 AI 一个 SQLite 笔记工具箱
加法演示没有体感,写个真有用的:一个本地笔记库,让 AI 能替你存、搜、取笔记。三个工具,全部用标准库 sqlite3,不装任何额外依赖:
from contextlib import closing
import sqlite3
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
mcp = MCPServer("NoteBox")
DB = "notes.db"
# 模块加载时建表,CREATE IF NOT EXISTS 幂等,跑多少次都安全
with closing(sqlite3.connect(DB)) as conn:
conn.execute("""CREATE TABLE IF NOT EXISTS notes(
id INTEGER PRIMARY KEY AUTOINCREMENT,
title TEXT NOT NULL,
body TEXT NOT NULL,
created_at TEXT DEFAULT (datetime('now', 'localtime'))
)""")
conn.commit()
@mcp.tool()
def add_note(title: str, body: str) -> str:
"""保存一条笔记,返回它的编号。"""
with closing(sqlite3.connect(DB)) as conn:
cur = conn.execute(
"INSERT INTO notes(title, body) VALUES(?, ?)",
(title, body),
)
conn.commit()
return f"已保存第 {cur.lastrowid} 条笔记「{title}」"
@mcp.tool()
def search_notes(keyword: str) -> list[str]:
"""按关键词搜索标题和正文,返回最近 20 条的编号和标题。"""
with closing(sqlite3.connect(DB)) as conn:
rows = conn.execute(
"SELECT id, title FROM notes "
"WHERE title LIKE ? OR body LIKE ? "
"ORDER BY id DESC LIMIT 20",
(f"%{keyword}%", f"%{keyword}%"),
).fetchall()
if not rows:
return ["没有匹配的笔记"]
return [f"#{r[0]} {r[1]}" for r in rows]
@mcp.tool()
def get_note(note_id: int) -> str:
"""按编号取出一条笔记的完整内容。"""
with closing(sqlite3.connect(DB)) as conn:
row = conn.execute(
"SELECT title, body FROM notes WHERE id = ?",
(note_id,),
).fetchone()
if row is None:
raise ToolError(f"没有编号为 {note_id} 的笔记")
return f"「{row[0]}」\n{row[1]}"
if __name__ == "__main__":
mcp.run()几个设计说明:
- docstring 不是摆设:它是模型看到的工具说明,写得越具体,模型调用得越准。比如 search_notes 里「返回最近 20 条」就是在告诉模型别指望一次拿全量;
ToolError是「说给模型听的报错」:抛普通异常模型只能看到一句模糊的执行失败,而ToolError的消息会原样传给模型,它能读懂并自己决定下一步(换关键词重搜、还是告诉你没这条);- 参数校验自动来:
note_id: int意味着模型传字符串过来会直接被拦在门外,你的函数体永远拿到干净的类型。
还是老办法验证:uv run mcp dev notes_server.py,在 Inspector 里调一遍 add_note,再去项目目录看 notes.db 是否长出来了。工具箱本地跑通,就差把它递给真正的 AI 客户端。
六、接进真实客户端:一条命令的事
所有桌面客户端接 stdio server 的姿势惊人地一致:告诉它启动你 server 的那条命令。官方推荐的通用启动命令长这样(绝对路径是关键,后面细说):
uv run --with "mcp[cli]" mcp run /绝对路径/notes_server.py这条命令的妙处是 uv run --with 会现场解析一个干净环境,不依赖你激活了哪个 venv、在哪个目录。
Claude Desktop:唯一能自动配置的
uv run mcp install notes_server.py它会导入你的文件读 server 名字,找到 Claude Desktop 的配置文件(macOS 在 ~/Library/Application Support/Claude/claude_desktop_config.json,Windows 在 %APPDATA%\Claude\claude_desktop_config.json),写入类似这样的条目——手写也照这个抄:
{
"mcpServers": {
"NoteBox": {
"command": "/绝对路径/uv",
"args": [
"run", "--frozen", "--with", "mcp[cli]==2.0.0",
"mcp", "run", "/绝对路径/notes_server.py"
]
}
}
}写完彻底退出 Claude Desktop 再重开(只关窗口没用),对话框旁边出现锤子图标就是连上了。要给工具箱配环境变量,用 uv run mcp install notes_server.py -v API_KEY=xxx,它会记进条目的 env 字段。
Cursor 和 VS Code:两个 JSON 文件
Cursor 在项目根目录建 .cursor/mcp.json:
{
"mcpServers": {
"notebox": {
"command": "uv",
"args": ["run", "--with", "mcp[cli]", "mcp", "run", "/绝对路径/notes_server.py"]
}
}
}VS Code 在 .vscode/mcp.json,就两点不同:外层键叫 servers 不叫 mcpServers,且每个条目要声明 "type": "stdio"。注意 VS Code 需要 1.99 以上配 GitHub Copilot 扩展,聊天切到 Agent 模式才会真正调用工具。
Claude Code / 远程模式
命令行党一行注册:
claude mcp add notebox -- uv run --with "mcp[cli]" mcp run /绝对路径/notes_server.py而如果你想让别的机器也能用这个工具箱,把启动方式换成 HTTP——server 文件一个字都不用改:
uv run mcp run notes_server.py --transport streamable-http
# 监听 http://localhost:8000/mcp再用 SDK 自带的 Client 两行验证连通:
import anyio
from mcp import Client
async def main():
async with Client("http://localhost:8000/mcp") as client:
print(client.server_capabilities.model_dump(exclude_none=True))
print(await client.call_tool("add_note", {"title": "测试", "body": "hello mcp"}))
anyio.run(main)v2 的 Client 连接时自动探测协议版本,对老服务器回落到握手流程——「写一个 server,新旧客户端通吃」在这套 SDK 里是字面意思。
七、三个高频翻车点,提前拆雷
- 相对路径是头号杀手。 host 启动你的 server 时工作目录是它自己的,不是你敲命令的目录。配置里所有路径(server 文件、uv 本体)一律绝对路径——官方文档直接把这条列为「最常见的单点故障」。host 找不到 uv 时,用
which uv(Windows 用where uv)拿到绝对路径填进去; - 改了配置必须完全重启 host。 Claude Desktop 尤其要彻底退出进程(托盘图标也退掉)再开,光关窗口重开不会重读配置文件;
- stdout 是协议通道,别污染。 stdio 模式下你的 stdout 就是 MCP 报文本身,代码里随手一个
print()调试输出会把协议流弄脏,host 直接断连。日志一律走 stderr(默认 logging 配置就是)。怀疑 server 有问题时,先自己在终端跑一遍启动命令:没有任何输出、也不退出,就是正常——它在等 host 先开口。
写在最后
写一个 MCP server 的实际体验,比「协议」两个字听起来轻得多:v2 之后整个流程收敛成了「一个装饰器 + 一条启动命令 + 一段 JSON」。本文的笔记工具箱只有几十行,但它已经是一个完整可用的私人 AI 后端——同一个文件,stdio 接桌面客户端,HTTP 接远程调用,测试还能内存直连。下一步你可以把工具换成查日志、管待办、操作家里的 NAS,模式一模一样。
唯一要提醒的还是开头那句:抄教程先看年份。v2 的 MCPServer 与老教程的 FastMCP 只差一个名字,但这个差别足以让新手在第一步就怀疑人生。认准 from mcp.server import MCPServer,其余的,交给装饰器。
参考来源:MCP Python SDK 官方文档(py.sdk.modelcontextprotocol.io:「What's new in v2」「Installation」「First steps」「Connect to a real host」诸页)、微软 GitHub 学习仓库 lets-learn-mcp-python、B站科技区与知乎 MCP 实战系列教程(选题灵感来源)。文章所有命令与配置均以官方文档为准自行组织。
以上内容为 GLM 5.3 Agent 整合定时发布。

