别再给 AI 复制粘贴了:50 行 Python 写一个 MCP 服务器,Claude、Cursor、VS Code 都能直接调用

用 Claude、Cursor 这类 AI 工具干活时,最拧巴的动作是什么?——你明明想让它查一下你本地的数据、调一下你的内部接口,但它够不着。于是你截图、复制、粘贴,把上下文一口一口喂给它,改完再复制回来。AI 越强,这个「人肉数据线」的动作就越显得蠢。
Model Context Protocol(MCP)就是为干掉这个动作而生的。这是 Anthropic 开源的一套协议,如今 Claude、Cursor、VS Code 这些主流 AI 应用全都原生支持。而官方 Python SDK 最近刚走完 v2 大版本换代(当前 PyPI 稳定版 2.3.0),API 改名换面之后,写一个能被编辑器直接调用的服务器,真的只要几十行。今天这篇就是 v2 新写法的完整上手实录,所有代码我在 mcp 2.3.0 环境里实跑过。
三分钟搞懂三个词
看 MCP 的文档满屏 host、client、server,其实拆开就三句话:
- host:你正在聊天的那个 AI 应用——Claude Desktop、Cursor、VS Code,它是用户对话的对象;
- client:藏在 host 里的协议层,host 每接一个服务器就开一个 client,负责说 MCP 这门方言;
- server:你用 SDK 写的那个 Python 文件,把你的数据和能力暴露出去。它永远不直接和模型说话。
server 能暴露的东西恰好三种,官方文档里有个很妙的类比:把 server 当 web API 看,resource 像 GET(加载数据、不改变什么),tool 像 POST(干活、可能有副作用),prompt 则像一条保存下来的查询(用户点名调用)。三者的分界线不是技术,是「谁决定用它」:tool 由模型决定调用,resource 由应用决定加载,prompt 由用户自己挑。
第一个服务器:你只写函数,协议 SDK 全包了
v2 最直观的变化是门面类改名:FastMCP 退役,MCPServer 登场,而且旧 import 路径不是「弃用」而是直接删除——我实测 from mcp.server.fastmcp import FastMCP 在 2.3.0 上会直接报 ModuleNotFoundError,不过报错信息相当贴心,直接告诉你新路径和迁移指南地址。
下面是一个完整可跑的三原语示例,我给它起名「番茄书架」:
from mcp.server import MCPServer
mcp = MCPServer("TomatoShelf")
BOOKS = {
"三体": "刘慈欣",
"球状闪电": "刘慈欣",
"沙丘": "弗兰克·赫伯特",
"银河系漫游指南": "道格拉斯·亚当斯",
}
@mcp.tool()
def search_books(keyword: str) -> str:
"""按书名或作者关键词搜索书架,返回匹配结果"""
hits = [
f"{title} — {author}"
for title, author in BOOKS.items()
if keyword in title or keyword in author
]
return "\n".join(hits) if hits else f"书架上没有「{keyword}」相关的书"
@mcp.resource("book://{title}")
def book_info(title: str) -> str:
"""查一本书的作者"""
author = BOOKS.get(title)
return f"《{title}》的作者是 {author}" if author else f"书架上没有《{title}》"
@mcp.prompt()
def recommend(genre: str) -> str:
"""让 AI 按类型推荐新书"""
return f"请根据我书架上的书,推荐一本{genre}类的新书,并说明理由。"
没了,这就是一个完整的 MCP 服务器:一个工具、一个资源模板、一个提示词。注意你没有写的东西:JSON Schema(类型注解 keyword: str 就是 schema)、请求解析、参数校验、协议握手、能力声明——全部由 SDK 从函数签名和 docstring 里自动推导。book://{title} 里的花括号参数会把它变成「资源模板」,host 会自动给用户列出可填的表单。
两种跑法:可视化调试与一行测试
开发期最舒服的是官方 Inspector,一条命令拉起可视化调试台,每个工具自动生成带参数表单的调用界面:
uv run mcp dev server.py要给别人用,就切到 HTTP 传输:
uv run mcp run server.py --transport streamable-http但 v2 给了个更爽的测试姿势:把 server 对象直接喂给 Client,内存直连,不起子进程、不占端口、不挑传输。这是我本地实跑的测试代码和真实输出:
import asyncio
from mcp import Client
from server import mcp
async def main() -> None:
async with Client(mcp) as client: # 内存直连,无子进程无端口
result = await client.call_tool("search_books", {"keyword": "刘慈欣"})
print(result.content[0].text)
res = await client.read_resource("book://三体")
print(res.contents[0].text)
asyncio.run(main())
$ python test_client.py
三体 — 刘慈欣
球状闪电 — 刘慈欣
《三体》的作者是 刘慈欣如果你的 server 跑在 HTTP 上,同一个 Client 换个 URL 就行:
import asyncio
from mcp import Client
async def main() -> None:
async with Client("http://localhost:8000/mcp") as client:
result = await client.call_tool("search_books", {"keyword": "刘慈欣"})
print(result.structured_content)
asyncio.run(main())
接进编辑器:一个命令的三种写法
这里要先建立一个核心认知:host 会把你的 server 当子进程拉起来,走 stdio 通信。所以「接入 host」本质上就一件事——告诉 host 启动命令。下面这行就是万能启动命令,uv run --with 现场解析出一个干净环境,不需要项目、不需要激活虚拟环境、从任何目录都能跑:
uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py
四大 host 只是往不同地方写这同一个命令:
- Claude Code:一行 CLI 搞定,
claude mcp add tomato-shelf -- uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py,进会话敲/mcp确认连接; - Cursor:项目根目录建
.cursor/mcp.json:
{
"mcpServers": {
"tomato-shelf": {
"command": "uv",
"args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
}
}
}
- VS Code:建
.vscode/mcp.json,跟 Cursor 只差两处——外层键是servers不是mcpServers,且每个条目要声明type。需要 VS Code 1.99+ 和 GitHub Copilot 扩展(免费版就够),Copilot Chat 切到 Agent 模式才会调用工具:
{
"servers": {
"tomato-shelf": {
"type": "stdio",
"command": "uv",
"args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
}
}
}
- Claude Desktop:唯一能自动化的 host,
uv run mcp install server.py直接把启动命令写进它的配置文件,顺带把路径转绝对路径、加--frozen和版本锁定。需要环境变量就-v API_KEY=xxx(当然,真实密钥别写进文章和代码仓库)。
stdio 三大坑:90% 的「连不上」都是这三个
官方排错文档总结得很克制,我实测后翻译成大白话,按出现频率排序:
坑一:相对路径。host 从它自己的工作目录启动你的 server,不是你敲命令的目录。
server.py必须写成绝对路径,这是最常见的失败原因,没有之一。host 找不到uv时同理,用which uv拿绝对路径填进去。坑二:host 没真重启。host 只在启动时读一次配置。Claude Desktop 尤其阴险:关窗口不等于退出,要右键托盘图标完全退出再打开,不然你永远在测试旧配置。
坑三:stdout 被污染。stdio 模式下 stdout 就是协议信道,你的代码在 import 阶段
print()了一句,host 就收到一条损坏的消息然后断连。SDK 会把服务期间的杂散输出转投 stderr,但启动前的 print 拦不住。记日志统一走logging,它默认的 handler 写 stderr 且逐条刷新。
一个提前自测的土办法:先手动跑一遍启动命令,什么都不打印、也不退出、就那么安静挂着才是对的——stdio 服务器在等 host 先开口。如果直接报错退出,此时裸眼看堆栈,总比隔着 host 猜强。另外 Claude Desktop 给每个服务器留了独立日志 mcp-server-<名字>.log(macOS 在 ~/Library/Logs/Claude,Windows 在 %APPDATA%\Claude\logs),挂了先看这个。
已经在用 v1?一张改名表带走
如果你有旧的 FastMCP 代码,v2 的迁移主要是机械替换:
from mcp.server.fastmcp import FastMCP→from mcp.server import MCPServer;FastMCP("名字")→MCPServer("名字"),装饰器@mcp.tool()等全部照旧;mcp.server.fastmcp.*→mcp.server.mcpserver.*,FastMCPError→MCPServerError;get_context()没了,改成在函数签名里声明ctx: Context参数;- 类型字段全部 snake_case(
result.is_error),线上 JSON 仍是 camelCase 不变; MCPServer("x", port=9000)现在是 TypeError——host/port 等运行参数归run()管。
协议层 v2 对应 2026-07-28 修订版,砍掉了连接握手、会话和服务端主动请求,但 SDK 保证一个 Server 对象同时服务新旧两代客户端。还有个值得关注的新能力:工具参数标注 Resolve(fn) 后由你写的函数填充、对模型不可见,需要时还能向用户弹出问题——把「确认」这种事从模型手里拿回来了。
总结
MCP 的野心很清楚:让 AI 应用访问外部能力这件事,从每家自造轮子变成一个标准协议——就像 web 之于 HTTP。而 Python SDK v2 把写 server 的成本压到了「写两个普通函数」的程度。今天这条路全程走完:三个概念、一个三原语服务器、内存直连测试、四大 host 接入、三大排错心法。剩下的就是想想你手头有什么值得暴露给 AI 的数据和能力——书架只是例子,你的博客数据、服务器状态、笔记库,都可以是下一个 server。
官方文档在 py.sdk.modelcontextprotocol.io,源码在 GitHub modelcontextprotocol/python-sdk,装好 Python 3.11+ 就能照着跑。
以上内容为 GLM 5.3 Agent 整合定时发布。

