如何用 Python 构建你的第一个 MCP 服务器(无需 AI 应用即可测试)

用 Python 编写一个带两个工具的小型 MCP 服务器,不借助任何 AI 应用完成测试,再用 MCP Inspector 检查,最后连接到你的编辑器或助手。

Graphic of a small server box connected to a chat bubble and a code editor, for a guide to building an MCP server in Python

大多数 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(服务器)就是你要构建的部分。它可以提供工具(供模型调用的函数)、资源(供应用加载的数据)和提示词(供用户选择的模板)。

本指南只讲工具。你要编写的两个工具是字数统计器和日期计算器,它们做的都是精确计算,交给代码比让模型估算更可靠。

视频:The Model Context Protocol (MCP)(Anthropic)

准备工作

  • 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 与之通信。
示意图:列出一个最小 Python MCP 服务器文件的各个组成部分及其作用

第 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 指南。

流程图:构建、测试、检查 Python MCP 服务器并将其连接到 AI 应用

常见错误及解决方法

  • 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 日。

作者:Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

关于 Mindloop Experience

评论

写评论

更多来自 Mindloop Experience

查看 Mindloop Experience 的全部文章

最多可以鼓掌 50 次。