在 python-sdk 中运行 MCP 服务器:`mcp.run()`、传输方式与 `mcp` 命令行工具全解析

原创2026-09-21 12:29:431,732 阅读
文章标签:人工智能大模型MCP 服务MCP Clients工具调用后端

在 python-sdk 中运行 MCP 服务器:mcp.run()、传输方式与 mcp 命令行工具全解析

本文围绕 Model Context Protocol(MCP)官方 Python SDK(仓库 gh_mirrors/pythonsd/python-sdk)中"运行服务器"这一核心环节展开:你将掌握 mcp.run() 的同步阻塞语义、stdio 与 streamable-http 两种传输方式的取舍与全部可选参数、log_level 与 debug 等服务器设置,以及 mcp dev / mcp run / mcp install / mcp version 四个 CLI 命令的完整用法。读完即可把你的服务器从"本机子进程"平滑迁移到"端口上的 HTTP 服务",并为接入 Claude Desktop 等真实主机做好准备。

传输方式:运行服务器时唯一要做的决定

mcp.run() 会启动服务器。整个过程中你唯一要做的决定是传输方式(transport)——即服务器与客户端之间的字节到底如何移动。SDK 提供三种选择:

传输方式 它是什么 何时使用
stdio MCP 主机(host)把你的文件当作子进程启动,通过它的 stdin 和 stdout 通信 本机服务器。默认值
streamable-http 一个真正的 HTTP 服务器,监听某个端口 任何要部署的东西
sse 较旧的 HTTP 传输方式 不要用

!!! warning SSE 已在 2025-03-26 协议修订版中被 Streamable HTTP 取代。mcp.run(transport="sse") 仍然可用,并且自带 sse_path= 和 message_path= 选项,但它只是为还没迁移的客户端保留的。不要在它之上构建任何新东西。

从源码看,run() 的签名就是围绕这三种传输组织的:src/mcp/server/mcpserver/server.py 中为 stdio、sse、streamable-http 分别声明了重载(overload),并在实现里用 match transport: 分发到对应的异步方法(server.py)。注意 run() 是同步函数,它内部通过 anyio.run(...) 驱动各自的异步实现。

mcp.run():同步阻塞的服务器入口

最基础的启动方式不传任何参数:

from mcp.server import MCPServer

mcp = MCPServer("Bookshop")


@mcp.tool()
def search_books(query: str) -> str:
    """Search the catalog by title or author."""
    return f"Found 3 books matching {query!r}."


if __name__ == "__main__":
    mcp.run()

(完整示例见 docs_src/run/tutorial001.py,原文中的 hl_lines="12-13" 高亮的就是 if __name__ == "__main__": 与 mcp.run() 两行。)

关于这段代码,有三个要点:

  • run() 是同步的。服务器活多久,它就阻塞多久。
  • 不带参数时,传输方式是 stdio。
  • 它必须放在 if __name__ == "__main__": 下面。因为所有会加载服务器的工具(mcp dev、mcp run、mcp install、你的测试)都是 import 这个文件,这道防护让"import 文件"不会变成"启动一个正在运行的服务器"。当 mcp run 从命令行执行时,它导入模块并自行调用 run(),你文件里的主程序块永远不会执行(详见下文 CLI 部分)。

stdio:本机子进程传输

stdio 传输没有任何需要配置的东西。主机把你的文件当作子进程启动,把请求写进它的 stdin,再从它的 stdout 读回应。

你可以自己运行看看后果:

python server.py

什么都不会打印,也不会退出。它在 stdin 上等主机先开口。

这也意味着 stdout 本身就是线路(the wire)。服务期间,SDK 会把线路移到一个私有的文件描述符上,并把所有 flush 到 stdout 的输出(例如子进程写入它继承来的 stdout、flush 过的 print())改道到 stderr,以免污染 MCP 数据流。但要注意两种例外:

  • 在开始服务之前就 flush 到 stdout 的输出(包装脚本的 echo、import 时未缓冲的 print)仍会落到线路上;
  • 一直缓冲到解释器退出时才清空的 print() 也一样会落到线路上。

所以,如果你想要真正可控的输出,logging 模块才是正确的工具:它的 handler 会在每条记录发生时立即 flush 到 stderr。完整说明见记录日志(Logging)。

试试看:MCP Inspector

uv run mcp dev server.py

MCP Inspector 做的事情和真正的主机一模一样:把 server.py 当作子进程启动,通过 stdio 连上它。你从头到尾没给它端口——因为这里根本不存在端口。

Streamable HTTP:把同一个服务器放到端口上

要把同一个服务器改为监听端口,只需在 run() 里指名传输方式(以及它的选项):

from mcp.server import MCPServer

mcp = MCPServer("Bookshop")


@mcp.tool()
def search_books(query: str) -> str:
    """Search the catalog by title or author."""
    return f"Found 3 books matching {query!r}."


if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=3001)

(完整示例见 docs_src/run/tutorial002.py。)

这一行会创建一个 Starlette 应用,并用 uvicorn 提供服务。客户端连接到 http://127.0.0.1:3001/mcp。

每种传输方式都有自己的关键字参数,全部挂在 run() 上:

  • host / port:在哪里监听。默认 127.0.0.1 和 8000。
  • streamable_http_path:MCP 端点所在路径。默认 /mcp。
  • json_response=True:每个 POST 都用单个 JSON 响应体回答,而不是 SSE 流。那个响应体只装得下响应本身、装不下别的,所以请求中途回调客户端的工具(ctx.elicit()、采样 sampling)在这一段会抛 NoBackChannelError,而绑定在正在进行的调用上的通知(ctx.report_progress() 的进度、每次调用的日志消息)会被丢弃;独立的 GET 流仍会承载不相关的那些通知。
  • stateless_http=True:每个请求一个全新的传输,不追踪会话(session)。
  • max_request_body_size:可接受的最大请求体,以字节计。默认 4 MiB;更大的请求在解析或创建会话之前就会收到 HTTP 413。只有在合法的 MCP 消息确实超过这个大小时才应调高它。
  • session_idle_timeout:旧版会话在没有任何进行中的请求时可闲置的秒数,超过后服务器就把它关掉。默认 1800。传 None 会停用它。详见会话生命周期与限制。
  • max_sessions:一个进程同时能持有多少个旧版会话。默认 10 000。传 None 会移除该限制。同一节有说明。
  • event_store、retry_interval、transport_security:分别对应可续传性与 DNS 重新绑定防护。这些可以先放着,等到部署到 localhost 以外再说;transport_security 在部署与扩展中有详细说明。

以上默认值与源码完全一致:run_streamable_http_async 的签名中 host="127.0.0.1"、port=8000、streamable_http_path="/mcp"、json_response=False、stateless_http=False、max_request_body_size=DEFAULT_MAX_REQUEST_BODY_SIZE、session_idle_timeout=DEFAULT_SESSION_IDLE_TIMEOUT、max_sessions=DEFAULT_MAX_SESSIONS(server.py)。它先通过 streamable_http_app(...) 组装出 Starlette 应用,再交给 uvicorn.Config / uvicorn.Server 对外服务(server.py)。

!!! warning 传输选项是给 run() 的,不是给 MCPServer(...) 的。构造函数描述的是服务器是什么:名称、版本、说明文字(instructions);run() 描述的是它如何被服务。如果搞反了,Python 会在 MCP 还没介入之前就回答你:

```text
TypeError: MCPServer.__init__() got an unexpected keyword argument 'port'
```

run() 是一条捷径。一旦你需要更多(把服务器挂载进现有应用、一个进程里跑两个服务器、为浏览器客户端开 CORS),就应该自己构建 ASGI 应用,再交给任意 ASGI 服务器去跑。那是加入现有应用的主题。

服务器设置:log_level 与 debug

关于运行,还有两件事与传输无关——它们是构造函数参数:

from mcp.server import MCPServer

mcp = MCPServer("Bookshop", log_level="DEBUG")


@mcp.tool()
def search_books(query: str) -> str:
    """Search the catalog by title or author."""
    return f"Found 3 books matching {query!r}."


if __name__ == "__main__":
    mcp.run()

(完整示例见 docs_src/run/tutorial003.py。)

  • log_level:在构造 MCPServer(...) 的当下就交给 logging.basicConfig()。它会配置 root logger,因此也会设置你自己 logger 的层级,而不只是 SDK 的。默认 "INFO"。
  • debug:转交给 HTTP 传输所创建的 Starlette 应用。默认 False。

两者最终都会落在 mcp.settings 上,运行时可以读回来。源码中的 Settings 模型对此有明确约束:debug: bool,而 log_level 的类型是 Literal<a href="https://link.gitcode.com/i/b8502d43c9568a6504b587334730ce71" target="_blank">"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]([server.py),也就是说合法的 log_level 取值就这五个。另外注意,uvicorn 的日志级别也会跟随 self.settings.log_level.lower() 被同步设置(server.py),因此 HTTP 传输下服务器与 uvicorn 的日志级别保持一致。

mcp 命令行工具

<a href="https://link.gitcode.com/i/b9729a67ebf592aa6181299e3b5ad199" target="_blank">cli] extra 会安装一个小型命令行工具,把这些能力全部包起来(实现见 [src/mcp/cli/cli.py,基于 typer 构建,pip install "mcp[cli]" 即可获得)。

mcp dev:在 MCP Inspector 下运行服务器

uv run mcp dev server.py
uv run mcp dev server.py --with pandas --with numpy
uv run mcp dev server.py --with-editable .
  • --with 把指定包加进它构建的环境;
  • --with-editable 把你自己的包以可编辑模式安装进去。

它需要 PATH 上有 npx:Inspector 是一个 Node.js 应用。从源码看,dev 命令会先导入你的服务器文件以收集依赖,然后用 uv run --with mcp ... 组装出启动命令,最终通过 npx @modelcontextprotocol/inspector 拉起 Inspector(cli.py);在 Windows 上还会尝试 npx.cmd / npx.exe 以兼容平台差异。

mcp run:直接执行服务器文件

mcp run 会导入文件、找出服务器对象(模块层级的 mcp、server 或 app),然后对 run() 调用它:

uv run mcp run server.py
uv run mcp run server.py:bookshop

当对象不叫 mcp、server 或 app 时,用 : 后缀指名它。注意:

  • 你的 if __name__ == "__main__": 块在这里永远不会执行:mcp run 自己调用 run(),而且它唯一转交的选项是 --transport(对应 -t)。
  • 从源码可以确认,run 命令先解析 file:object 形式的文件说明符(兼容 Windows 盘符),把父目录加入 sys.path 后以模块方式导入,再按 mcp → server → app 的顺序寻找 MCPServer 实例;找不到时就会报错并提示使用标准变量名或 file:object 语法(cli.py)。

mcp install:注册到 Claude Desktop

mcp install 把服务器注册到 Claude Desktop,让那个应用替你启动它:

uv run mcp install server.py --name "Bookshop"
uv run mcp install server.py -v API_KEY=abc123 -f .env
  • -v KEY=VALUE 和 -f .env 会把环境变量记录在那条注册项里。
  • Claude Desktop 会在它自己的进程里启动服务器——你的 shell 环境并不在那里,所以需要显式传入环境变量。
  • 如果服务器对象上声明了 dependencies 属性,install 也会把它合并进 --with 列表一起记录(cli.py)。

mcp install 只认得 Claude Desktop 这一个主机。其他每个主机(Claude Code、Cursor、VS Code)都在各自的配置文件里接受同样的启动命令,连接真正的主机一节对每一个都有说明。

mcp version:查看版本

mcp version

打印已安装的 SDK 版本(内部通过 importlib.metadata.version("mcp") 读取,见 cli.py)。

!!! tip mcp dev 和 mcp run 只懂 MCPServer。如果你是用低阶的 Server 构建的,就需要自己运行它,见低阶 Server。

重点回顾

  • 传输方式决定字节如何到达你的服务器:本机子进程用 stdio,端口上用 streamable-http。SSE 已被取代。
  • mcp.run() 选择传输方式。不带参数就是 stdio,并且会阻塞。
  • 每个传输选项(host、port、streamable_http_path……)都是 run() 的参数,绝不是 MCPServer(...) 的。
  • 把 run() 放在 if __name__ == "__main__": 下面。所有加载服务器的工具都会先 import 这个文件。
  • log_level= 和 debug= 是构造函数参数;它们最终落在 mcp.settings 上,运行时可读回。
  • mcp dev 开 Inspector,mcp run 执行文件,mcp install 注册给 Claude Desktop,mcp version 查看版本。
  • 传输方式永远不会改变服务器是什么:本页的三个示例文件(tutorial001.py、tutorial002.py、tutorial003.py)公开的是完全相同的工具,只是启动方式不同。

当 run() 本身成了限制(服务器要放进一个已存在的应用里),就看加入现有应用;真正的主机名和不止一个 worker 是部署与扩展的主题;而如果有些客户端还停在规格版本 2025-11-25 或更早,服务旧版客户端有好消息。

登录后查看全文
python-sdk