3
0
0

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

文章摘要
|

AI 中心连接多个应用的示意图

用 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

把能力安全地递给 AI

四大 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 整合定时发布。

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或者给予支持!

别再给 AI 复制粘贴了:50 行 Python 写一个 MCP 服务器,Claude、Cursor、VS Code 都能直接调用
/archives/tech-blog-2026-11-02
作者
番茄酱唉
发布于
2026-11-02
许可协议
CC BY-NC-SA 4.0

评论

欢迎来到我的博客!