大多数 Model Context Protocol(MCP)教程只教你安装别人写好的服务器。本文则教你用 Python 构建自己的 MCP 服务器:一个带两个工具的小型服务器,任何支持 MCP 的 AI 应用都能调用。你将亲手搭建它,在不借助任何 AI 应用的情况下完成测试,用官方 MCP Inspector 检查它,然后把它连接到编辑器或 AI 助手。
要点速览
- 官方 MCP Python SDK 2.x 把服务器类改名为 MCPServer,因此许多旧教程里的代码已无法直接运行。
- 给函数加上 @mcp.tool() 装饰器就能把它变成工具;工具的名称、描述和输入 schema 都来自你的代码。
- 先用 SDK 的 Client 类在内存中测试服务器,再通过 stdio 用官方 MCP Inspector 测试。
- 只要给 Cursor、VS Code 或 Claude Desktop 提供一条使用绝对路径的 uv 启动命令,就能完成连接。
截至 2026 年 11 月 15 日,官方 Python SDK 的版本为 2.3.0(2026 年 10 月 2 日发布),MCP Inspector 的版本为 2.15.0(2026 年 11 月 12 日发布)。SDK 2.x 更改了主服务器类的名称,所以许多旧教程已无法照原样运行。下文中的项目、测试和 Inspector 命令均基于这些版本实际运行过。
什么是 MCP 服务器
MCP 是一个开源标准,用于把 AI 应用连接到外部系统。掌握 SDK 文档中的三个术语,就足以跟上本文:
- host(宿主)是你与之对话的 AI 应用,例如聊天助手或代码编辑器。
- client(客户端)位于宿主内部,负责使用 MCP 协议通信。
- server(服务器)就是你要构建的部分。它可以提供工具(供模型调用的函数)、资源(供应用加载的数据)和提示词(供用户选择的模板)。
本指南只讲工具。你要编写的两个工具是字数统计器和日期计算器,它们做的都是精确计算,交给代码比让模型估算更可靠。
准备工作
- uv:官方 MCP 教程使用的 Python 项目管理工具。如果缺少合适的 Python 版本,它会自动帮你下载。SDK 需要 Python 3.10 或更高版本。
- Node.js:仅第 4 步的 Inspector 需要。Inspector 2.15.0 要求 Node
^22.23.4 || ^24.22.1 || >=26.12.1。 - 一个支持 MCP 的应用,用于第 5 步(可选)。
在 macOS 或 Linux 上安装 uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
在 Windows 上,于 PowerShell 中运行:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
安装完成后重启终端,系统才能找到 uv 命令。
数字一览
2.3.0所用 Python SDK 版本
2.15.0所用 MCP Inspector 版本
3.10最低 Python 版本
第 1 步:创建项目
uv init --bare handy-tools
cd handy-tools
uv add "mcp[cli]"
--bare 只会创建一个 pyproject.toml,这个项目只需要它。cli 附加项会添加 mcp 命令行工具。确认安装成功:
uv run mcp version
预期输出:
MCP version 2.3.0
第 2 步:编写服务器
在项目文件夹中创建名为 server.py 的文件:
from datetime import date
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
mcp = MCPServer("Handy Tools")
@mcp.tool()
def count_words(text: str) -> int:
"""Count the words in a piece of text."""
return len(text.split())
@mcp.tool()
def days_between(start: str, end: str) -> int:
"""Count the days from one date to another. Dates use YYYY-MM-DD format."""
try:
first = date.fromisoformat(start)
second = date.fromisoformat(end)
except ValueError:
raise ToolError("Dates must look like 2026-11-15 (YYYY-MM-DD).")
return (second - first).days
if __name__ == "__main__":
mcp.run()
各部分的作用:
MCPServer("Handy Tools")负责创建服务器。在 SDK 2.x 中,它从mcp.server导入。@mcp.tool()把函数变成工具。SDK 从函数名读取工具名称,从 docstring 读取描述,从类型注解生成输入 schema。你一行 JSON 都不用写。ToolError会把一条易读的消息返回给模型,让它修正参数后重试。- 不带参数调用
mcp.run()会通过 stdio 启动服务器:宿主把你的文件作为子进程启动,并通过 stdin 和 stdout 与之通信。

第 3 步:用 Python 测试
SDK 自带一个 Client 类,可以在内存中直接连接你的服务器对象,不需要子进程、端口,也不需要 AI。在 server.py 旁边创建 check.py:
import asyncio
from mcp import Client
from server import mcp
async def main() -> None:
async with Client(mcp) as client:
tools = await client.list_tools()
print([tool.name for tool in tools.tools])
result = await client.call_tool("count_words", {"text": "the quick brown fox"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "2026-11-15", "end": "2027-01-01"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "tomorrow", "end": "2027-01-01"})
print(result.is_error, result.content[0].text)
asyncio.run(main())
运行它:
uv run check.py
预期输出:
['count_words', 'days_between']
{'result': 4}
{'result': 47}
True Error executing tool days_between: Dates must look like 2026-11-15 (YYYY-MM-DD).
你还会看到一行关于调用失败的 INFO 日志,那是服务器在记录 ToolError。注意,错误的日期并没有在客户端抛出异常:失败的工具调用会作为普通结果返回,其中 is_error 被设为 True。
你知道吗?
失败的工具调用不会在客户端抛出异常。它会作为普通结果返回,is_error 被设为 True,并附带 ToolError 的消息。
第 4 步:用 MCP Inspector 检查
MCP Inspector 是 MCP 项目官方的测试工具。它的 CLI 模式会像真正的宿主那样启动你的服务器,并打印返回的内容。在项目文件夹中运行:
npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/list
首次运行时会询问是否允许下载该软件包。随后你应该会看到一段 JSON,其中列出 count_words 和 days_between,每个工具都带有 SDK 根据类型注解生成的输入 schema。
现在调用一个工具:
npx @modelcontextprotocol/inspector --cli uv run server.py \
--method tools/call --tool-name days_between \
--tool-args-json '{"start":"2026-11-15","end":"2027-01-01"}'
预期输出:
{
"content": [
{
"type": "text",
"text": "47"
}
],
"structuredContent": {
"result": 47
},
"isError": false
}
SDK 还可以启动 Inspector 的网页界面:
uv run mcp dev server.py
它会打印一个本地地址,例如 http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=...,并在浏览器中打开。在 Servers 页面,打开你的服务器旁边的连接开关,进入 Tools,选择 count_words,输入一些文字,然后点击 Execute Tool(执行工具)。完成后在终端按 Ctrl+C。
第 5 步:连接到 AI 应用
连接宿主,就是告诉它启动你的服务器所用的命令。对这个项目来说,命令是:
uv --directory /ABSOLUTE/PATH/TO/handy-tools run server.py
在项目文件夹中运行 pwd 获取真实路径。先自己试一下这条命令:什么都不打印,也不会返回,这是正常的,因为服务器正在等待宿主发起通信。按 Ctrl+C 停止。
许多应用都接受同一段 JSON 来配置这条命令:
{
"mcpServers": {
"handy-tools": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/handy-tools", "run", "server.py"]
}
}
}
放在哪里取决于具体应用:
- Cursor:根据 Cursor 的 MCP 文档,可将其保存为项目中的
.cursor/mcp.json,或保存为~/.cursor/mcp.json以全局使用。该文档还为本地服务器列出了"type": "stdio"字段,不过文档自己的示例里并没有写。 - VS Code:根据 VS Code 文档,在命令面板中运行 MCP: Add Server,选择 Command (stdio),然后输入启动命令。
- Claude Desktop:运行
uv run mcp install server.py,它会自动为你写好配置项。这是 SDK 唯一能自动配置的宿主。
重启应用,然后问它类似这样的问题:
Use the days_between tool: how many days from 2026-11-15 to 2027-01-01?
答案应该是 47。请记住,这些工具在你的电脑上运行,拥有你账户的权限,所以只开放你放心让模型触发的操作。想看一个更大型的现成服务器示例,可以阅读我们的 Chrome DevTools MCP 指南。

常见错误及解决方法
ModuleNotFoundError: No module named 'mcp.server.fastmcp':这段代码是为 SDK 1.x 写的。在 2.x 中,类名是MCPServer,用from mcp.server import MCPServer导入。更新导入语句,或者固定版本mcp<2以继续运行旧代码。TypeError: The @tool decorator was used incorrectly:你写成了不带括号的@mcp.tool。请使用@mcp.tool()。- 应用里看不到你的服务器:常见原因是使用了相对路径。请使用项目的绝对路径;如果应用找不到
uv,就把uv替换为which uv(macOS 和 Linux)或where uv(Windows)给出的完整路径。修改配置后,要完全退出应用再重新打开。 - 连接中断或工具列表为空:通过 stdio 通信时,stdout 承载的就是协议本身。一个多余的
print()就可能破坏它。请改用 Python 的logging模块,它会写入 stderr。 - 出现
npm warn deprecated @modelcontextprotocol/inspector@0.15.0: v1 is deprecated,或工具调用因Field required失败:你的 Node.js 版本太旧,无法运行 Inspector 2.x。在 Node 20 上的一次测试中,npx悄悄安装了旧的 0.15.0 版本,而它会忽略--tool-args-json。用node --version检查版本,并升级到受支持的版本。 - 运行
mcp dev时出现npx not found:Inspector 是一个 Node.js 应用,请先安装 Node.js。 - 出现
Error executing tool <name>且没有任何消息:工具因一个你没有预料到的异常而崩溃。traceback 在服务器日志中,不在返回结果里。
你知道吗?
通过 stdio 通信时,stdout 承载的就是协议本身,所以服务器里一个多余的 print() 就可能破坏连接。Python 的 logging 模块则会写入 stderr。
总结
一个可用的 MCP 服务器,就是一个带有几个装饰函数的 Python 文件。编写工具,用 Client(mcp) 在内存中检查,用 Inspector 通过 stdio 确认,然后把启动命令交给任意宿主即可。接下来,你可以添加资源和提示词,或者用 mcp.run(transport="streamable-http") 通过 HTTP 提供同一套代码。如果你的 Agent 更需要书面指令而不是新函数,我们的 Claude Code 中的 Agent Skills 指南介绍了这方面的内容。
常见问题
MCP 的 host、client 和 server 有什么区别?
host(宿主)是你与之对话的 AI 应用,例如聊天助手或代码编辑器。client(客户端)位于宿主内部,负责使用 MCP 通信。server(服务器)是你构建的部分,可以提供工具、资源和提示词。
为什么会出现 No module named mcp.server.fastmcp?
这段代码是为 SDK 1.x 写的。在 2.x 中,类名是 MCPServer,用 from mcp.server import MCPServer 导入。更新导入语句,或者固定版本 mcp<2 以继续运行旧代码。
不用 AI 应用能测试 MCP 服务器吗?
可以。SDK 的 Client 类能在内存中连接你的服务器对象,无需子进程、端口或 AI。之后再用 MCP Inspector 的 CLI 模式,像真正的宿主那样通过 stdio 启动服务器。
MCP Inspector 需要哪个版本的 Node.js?
Inspector 2.15.0 要求 Node ^22.23.4、^24.22.1 或 >=26.12.1。在更旧的 Node 上,npx 可能会悄悄安装旧的 0.15.0 版本,而它会忽略 –tool-args-json。
小测验
在 SDK 2.x 中,哪个类用于创建 MCP 服务器?
- FastMCP
- ToolError
- MCPServer
SDK 2.x 把主服务器类改名为 MCPServer,从 mcp.server 导入。
一个多余的 print() 会对 stdio MCP 服务器造成什么影响?
- 破坏协议数据流
- 没有影响,输出会被忽略
- 重启服务器
通过 stdio 通信时,stdout 承载的就是协议本身,多余的输出可能会破坏它。
SDK 从哪里获取工具的输入 schema?
- 你自己编写的 JSON 文件
- 函数的类型注解
- 宿主的配置文件
SDK 从类型注解读取输入 schema,所以你不用写 JSON。
资料来源
链接最后检查于 2026 年 11 月 15 日。
- Build an MCP server (official tutorial)
- What is the Model Context Protocol?
- MCP Python SDK README, v2.3.0
- Python SDK: First steps
- Python SDK: Connect to a real host
- Python SDK: Testing
- Python SDK: Running your server
- Python SDK: Handling errors
- Python SDK: Troubleshooting
- mcp on PyPI
- MCP Inspector README, 2.15.0
- Inspector: smoke-testing an MCP server from the shell
- Installing uv
- uv: creating projects
- Cursor: Model Context Protocol
- VS Code: add and manage MCP servers





写评论