MCP Python SDK 服务器运行指南:传输方式、`mcp.run()` 与 `mcp` 命令行工具
MCP Python SDK 服务器运行指南:传输方式、mcp.run() 与 mcp 命令行工具
mcp.run() 是 MCP Python SDK 中启动服务器(MCPServer)的唯一入口,而围绕它需要做的最关键决策是传输方式(transport)——服务器与客户端之间的字节究竟如何流动。本指南基于 SDK 官方文档《运行服务器》展开,系统讲解 stdio 与 streamable-http 两种传输方式的选择、mcp.run() 的全部传输选项、log_level/debug 等服务器设置,以及 mcp dev、mcp run、mcp install、mcp version 四个 CLI 子命令的实战用法。读完本文,你将能独立把一个 MCP 服务器从本地子进程形态切换为可部署的 HTTP 服务,并理解底层实现原理。
选择传输方式:服务器与客户端之间的字节如何流动
官方文档用一个表格给出了三种传输方式的定位:
| 传输方式 | 是什么 | 何时使用 |
|---|---|---|
stdio |
宿主把你的文件作为子进程启动,通过它的 stdin 和 stdout 通信 | 本地服务器。默认值 |
streamable-http |
真正的 HTTP 服务器,监听一个端口 | 任何要部署的东西 |
sse |
较旧的 HTTP 传输方式 | 不要用 |
警告:SSE 已被取代。 SSE 在 2025-03-26 协议修订版中已被 Streamable HTTP 取代。
mcp.run(transport="sse")仍然可用,也有自己的sse_path=和message_path=选项,但它只是为还没迁移的客户端留着的。不要在它之上构建任何新东西。
从源码看,run() 的实现正是围绕这三种传输方式分派逻辑的。在 server.py 中:
def run(
self,
transport: Literal["stdio", "sse", "streamable-http"] = "stdio",
**kwargs: Any,
) -> None:
"""Run the MCP server. Note this is a synchronous function."""
TRANSPORTS = Literal["stdio", "sse", "streamable-http"]
if transport not in TRANSPORTS.__args__:
raise ValueError(f"Unknown transport: {transport}")
match transport:
case "stdio":
anyio.run(self.run_stdio_async)
case "sse":
anyio.run(lambda: self.run_sse_async(**kwargs))
case "streamable-http":
anyio.run(lambda: self.run_streamable_http_async(**kwargs))
可见 run() 是同步函数,内部通过 anyio.run 包装异步实现,这解释了文档强调的"它是同步的"这一特性。同时,run() 的重载签名(server.py)分别约束了 sse 与 streamable-http 各自可用的关键字参数,类型系统会在编译期帮你检查传输选项是否写错。
mcp.run() 入门:一个最小的服务器
以下是官方文档中的最小服务器示例(tutorial001.py):
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()
这段代码有四个要点:
run()是同步的:服务器存活多久,它就阻塞多久。它内部通过anyio.run()驱动事件循环,直到服务器停止才返回。- 不带参数时,传输方式是
stdio:这是默认值,无需显式指定。 - 它放在
if __name__ == "__main__":之下:因为所有加载服务器的东西(mcp dev、mcp run、mcp install、你的测试)都会导入这个文件。这个保护条件防止一次导入变成一个运行中的服务器——模块被导入时不会执行run(),只有直接运行该文件时才会启动。 MCPServer(...)的构造参数描述服务器"是什么":名称(name)、标题(title)、说明(description)、版本(version)等。从构造函数签名(server.py)可以看到,MCPServer.__init__接受name、title、description、instructions、website_url、icons、version、debug、log_level等一系列参数,但没有port、host这类传输选项——它们只属于run()。
深入 stdio:stdout 就是线路
stdio 传输没有什么需要配置的。宿主把你的文件作为子进程启动,把请求写入它的 stdin,再从它的 stdout 读取响应。
自己运行一下,就能看出这意味着什么:
python server.py
什么也不打印,也不返回。它在 stdin 上等着宿主先开口。从源码看,run_stdio_async(server.py)的实现非常直观:
async def run_stdio_async(self) -> None:
"""Run the server using stdio transport."""
async with stdio_server() as (read_stream, write_stream):
await self._lowlevel_server.run(
read_stream,
write_stream,
self._lowlevel_server.create_initialization_options(),
)
它借助 stdio_server() 建立读写流,再把低层 Server 挂到这两个流上运行。
为什么服务期间不能往 stdout 乱打印
这也意味着 stdout 就是线路(the wire)。服务期间,SDK 把线路移到一个私有描述符上,并把刷新到 stdout 的输出(子进程写入它继承的 stdout、刷新过的 print())转到 stderr,在那里不会破坏数据流。但有三类输出仍然会"漏"到线路上:
- 在开始服务之前就刷新到 stdout 的输出(包装脚本的 echo、导入时的无缓冲 print);
- 一直缓冲到解释器退出时才排空的
print(); - 其他任何直接写入继承 stdout 的行为。
对于真正想要的输出,logging 模块才是正确的工具:它的 handler 会在每条记录产生时就把它刷新到 stderr。SDK 内部也正是这么做的——configure_logging(logging.py)在安装了 rich 时使用 RichHandler(console=Console(stderr=True)),明确把日志输出到 stderr,从而与作为线路的 stdout 彻底隔离:
def configure_logging(
level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO",
) -> None:
handlers: list[logging.Handler] = []
try:
from rich.console import Console
from rich.logging import RichHandler
handlers.append(RichHandler(console=Console(stderr=True), rich_tracebacks=True))
except ImportError:
pass
if not handlers:
handlers.append(logging.StreamHandler())
logging.basicConfig(level=level, format="%(message)s", handlers=handlers)
更完整的日志主题可参考日志记录。
试一试:用 Inspector 连接你的 stdio 服务器
uv run mcp dev server.py
Inspector 做的事和真实宿主完全一样:它把 server.py 作为子进程启动,通过 stdio 连接它。
你从没给过它端口。根本就没有端口。
这正是 stdio 的本质——无需网络层,宿主与服务器之间就是进程内的两个管道。
Streamable HTTP:把同一个服务器放到端口上
要把同一个服务器放到端口上,在 run() 里指明传输方式(及其选项)(tutorial002.py):
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)
这一行会构建一个 Starlette 应用并用 uvicorn 提供服务。客户端连接到 http://127.0.0.1:3001/mcp。
从源码看,run_streamable_http_async(server.py)的流程是:先调用 self.streamable_http_app(...) 构建 Starlette 应用,再用 uvicorn.Config + uvicorn.Server 启动:
starlette_app = self.streamable_http_app(
streamable_http_path=streamable_http_path,
json_response=json_response,
stateless_http=stateless_http,
event_store=event_store,
retry_interval=retry_interval,
max_request_body_size=max_request_body_size,
session_idle_timeout=session_idle_timeout,
max_sessions=max_sessions,
transport_security=transport_security,
host=host,
)
config = uvicorn.Config(starlette_app, host=host, port=port, log_level=self.settings.log_level.lower())
server = uvicorn.Server(config)
await server.serve()
注意 uvicorn 的 log_level 直接取自 self.settings.log_level——这印证了后文"服务器设置"一节中 log_level 同时影响 HTTP 传输服务行为的事实。
run() 上的传输选项详解
每种传输方式都有自己的关键字参数,全都在 run() 上:
host/port:监听的位置。默认127.0.0.1和8000。streamable_http_path:MCP 端点所在的路径。默认/mcp。json_response=True:用单个 JSON 正文回应每个 POST,而不是 SSE 流。这个正文只容得下响应本身,别的什么都放不下,所以:- 在请求中途回调客户端的工具(
ctx.elicit()、采样 sampling)会在这一段抛出NoBackChannelError; - 与进行中的调用绑定的通知(
ctx.report_progress()的进度、每次调用的日志消息)会被丢弃; - 独立的
GET流仍然承载与之无关的通知。
- 在请求中途回调客户端的工具(
stateless_http=True:每个请求一个全新的传输,不跟踪会话。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。
常见错误:传输选项不属于 MCPServer(...)
警告:传输选项传给
run(),不是MCPServer(...)。构造函数描述服务器是什么:名称、版本、说明。run()描述它如何对外提供服务。搞反了,Python 在 MCP 介入之前就会报错:
TypeError: MCPServer.__init__() got an unexpected keyword argument 'port'
从 server.py 的构造函数签名可以确认:MCPServer.__init__ 的关键字参数只有 name、title、description、instructions、website_url、icons、version、debug、log_level、warn_on_duplicate_*、dependencies、lifespan、auth、resource_security、request_state_security、cache_hints、subscriptions、middleware 等,没有任何传输相关参数。错误地把 port 等参数传给构造函数,Python 解释器会直接拒绝。
run() 是捷径
run() 是捷径。一旦需要更多能力——把服务器挂载到现有应用里、一个进程里跑两个服务器、为浏览器客户端配置 CORS——就要自己构建 ASGI 应用,再交给任意 ASGI 服务器运行。这就是添加到现有应用 的内容。
服务器设置:与传输方式无关的构造函数参数
运行方面有几件事与传输方式无关,它们是构造函数参数(tutorial003.py):
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()
log_level:在构造MCPServer(...)的那一刻传给logging.basicConfig()。它配置的是根 logger,所以也会设置你自己的 logger 的级别,而不只是 SDK 的。默认"INFO"。允许的取值从源码看是"DEBUG"、"INFO"、"WARNING"、"ERROR"、"CRITICAL"五个级别(server.py)。值得注意的是,configure_logging是在MCPServer.__init__中同步调用的(server.py),所以一旦构造完成,根 logger 的级别就立即生效。debug:转发给 HTTP 传输构建的 Starlette 应用。默认False。
两者都落在 mcp.settings 上,可以在运行时读回。从源码看,MCPServer.__init__ 会构造一个 Settings 模型(server.py),把 debug、log_level、warn_on_duplicate_*、dependencies、lifespan、auth 一并存入 self.settings,因此运行时可以通过 mcp.settings.log_level、mcp.settings.debug 读取回这些配置。
mcp 命令:围绕运行方式的 CLI 工具
[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 应用。
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。
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 里的环境变量那里没有——所以需要显式传入。- Claude Desktop 是
mcp install唯一认识的宿主。其他宿主(Claude Code、Cursor、VS Code)都在各自的配置文件里接受同样的启动命令,连接到真实的宿主 逐一介绍了它们。
mcp version:查看版本
uv run mcp version
打印已安装的 SDK 版本。
提示:
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__":之下。所有加载服务器的东西都会先导入这个文件。 log_level=和debug=是构造函数参数;它们落在mcp.settings上。mcp dev用于 Inspector,mcp run执行文件,mcp install用于 Claude Desktop,mcp version查看版本。- 传输方式永远不会改变服务器"是什么":本页的三个教程文件(tutorial001.py、tutorial002.py、tutorial003.py)暴露的是完全相同的工具——改变传输方式只是改变了字节到达服务器的方式,工具本身、工具参数、服务器能力完全一致。
下一步:当 run() 成为限制时
- 当
run()本身成了限制(服务器要放进一个已经存在的应用里),看添加到现有应用。 - 需要真正的主机名和不止一个 worker,看部署与扩展。
- 如果有些客户端还停留在 2025-11-25 或更早的规范版本,为旧版客户端提供服务 有好消息。