连接真实 Host用 python-sdk 的mcp run命令将 MCP 服务器接入 Claude Desktop、Claude Code、Cursor 与 VS Code【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdkhost是 MCP 服务器最终运行所在的应用程序——Claude Desktop、Claude Code、各类 IDE 都属于 host。用户直接与 host 对话而 host 内部的 MCP 客户端把你的服务器作为子进程启动并通过该进程的 stdin/stdout 与之通信。这意味着连接真实 host本质上只有一个动作告诉 host 一个启动你服务器的命令。本页将围绕mcp run这个核心命令完整演示如何用官方 Python SDKpython-sdk把同一个服务器文件接入四种主流 host并给出配置 JSON、命令行参数与故障排查的完整方案。一个服务器适配所有 host先看本页反复出现的服务器文件完整代码见 docs_src/real_host/tutorial001.pyfrom mcp.server import MCPServer from mcp.server.mcpserver.exceptions import ToolError mcp MCPServer(Bookshop) CATALOG { Dune: Frank Herbert, Neuromancer: William Gibson, The Left Hand of Darkness: Ursula K. Le Guin, } mcp.tool() def search_books(query: str) - list[str]: Search the catalog by title or author. needle query.lower() return [title for title, author in CATALOG.items() if needle in title.lower() or needle in author.lower()] mcp.tool() def get_author(title: str) - str: Look up the author of a book in the catalog. if title not in CATALOG: raise ToolError(fNo book titled {title!r} in the catalog.) return CATALOG[title] mcp.resource(catalog://titles) def titles() - str: Every title in the catalog, one per line. return \n.join(sorted(CATALOG)) if __name__ __main__: mcp.run()两个工具、一个资源全部装在一个文件里。对于下面所有的 host这个文件有三个关键点mcp.run()不带参数启动的是 stdio 服务器它阻塞运行从 stdin 读取协议消息向 stdout 写协议消息。这正是本页所有 host 说的语言。host 把你的文件作为子进程启动并持有这两条管道所以连接永远只是给你一个命令——你从不选择端口也没有任何端口在监听。从 SDK 源码看MCPServer.run()的transport参数默认值就是stdio并最终通过anyio.run(self.run_stdio_async)进入阻塞的事件循环见 src/mcp/server/mcpserver/server.py。run()放在if __name__ __main__:之下下面所有 host 都是导入这个文件而不是执行它如果没有这层保护任何代码一旦加载该模块就会立刻启动一个服务器。服务器对象是模块级全局变量名为mcp这是mcp run查找的默认名字server和app同样有效。如果命名为别的你需要显式指定mcp run server.py:bookshop。在 CLI 实现中导入模块后会依次探测mcp、server、app三个候选名并校验其类型确实是MCPServer见 src/mcp/cli/cli.py。这一页的 Python 代码到此为止接下来全是 host 配置。配套的测试 tests/docs_src/test_real_host.py 展示了 host 视角下这台服务器暴露的内容list_tools能列出search_books、get_author两个工具名称、描述、输入 schema 全部来自代码catalog://titles是一个可直接列出、可读取的资源。启动命令一个命令走遍所有 host下面每个 host 接收的都是同一个命令uv run --with mcp[cli] mcp run /absolute/path/to/server.py所有 host 共用一条命令的原因在于uv run --with它会在一个全新的临时环境中即时解析安装 SDK从任何目录都能运行既不需要项目也不需要激活虚拟环境。这一点在 host 场景下比在其他地方更重要——因为 host 是从它自己的工作目录、用一个近乎空白的环境启动你的服务器而不是从你的 shell。这条命令也正是mcp install自动写进 Claude Desktop 配置的那条命令见下文所以手工输入与工具生成的内容一致唯一差别是工具额外固定的精确版本号。小贴士host 找不到uv怎么办host 用一个极简的PATH启动服务器uv可能不在其中。此时把裸的uv替换为which uvmacOS/Linux或where uvWindows给出的绝对路径——这正是mcp install写入的内容。源码中get_uv_path()会调用shutil.which(uv)解析出可执行文件完整路径见 src/mcp/cli/claude.py。注意本页讲的是本地故事本页所有内容都是在你运行 host 的同一台机器上启动服务器host 通过 stdio 拉起你的文件这对个人工具或单机工具完全正确。要把服务器交给没有你文件的人你分发的是URL而不是命令同一个mcp对象通过 Streamable HTTP 提供服务。运行你的服务器 用一张表帮你做这个决策部署与扩展 是从那里通向真正主机名的路径。另外host 无非是一个内置了 MCP 客户端的应用所以你自己写的 Python 也能扮演 host客户端传输 用Client(StdioServerParameters(...))把同一个文件作为子进程启动而 测试 完全在内存中连接它不需要任何进程。Claude DesktopSDK 唯一能替你配置的 hostClaude Desktop 是 SDK 中唯一能自动配置的 host一条命令即可uv run mcp install server.py仅此而已。mcp install会导入文件读取服务器名称找到 Claude Desktop 的配置文件并把启动命令写进去同时自动把你的路径转换为绝对路径你无需手工处理。这不是什么黑魔法下面是它写入的配置条目{ mcpServers: { Bookshop: { command: /absolute/path/to/uv, args: [ run, --frozen, --with, mcp[cli]2.0.0, mcp, run, /absolute/path/to/server.py ] } } }这是上一节的启动命令加了三点uv的绝对路径--frozen确保uv永不改写它碰巧旁边的锁文件以及对当前已安装mcp版本的精确固定。版本固定逻辑在 src/mcp/cli/claude.py 的mcp_requirement()中它读取当前已安装发行版的版本号生成mcp[cli]version形式的依赖约束开发版或本地构建则回退为不加版本号因为这类版本不会发布到 PyPI。配置写入claude_desktop_config.json位置在macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.jsonLinux$XDG_CONFIG_HOME/Claude/claude_desktop_config.jsonXDG_CONFIG_HOME缺省为~/.config见 src/mcp/cli/claude.py这个文件完全可以手写。mcp install的存在是为了让你避免手写时最经典的错误——用了相对路径。写完配置后彻底退出Claude Desktop不只是关窗口再重新打开。警告如果 Claude Desktop 的配置目录还不存在mcp install会以Claude app not found失败。先安装 Claude Desktop 并运行一次——目录就是这时创建的。小贴士环境变量与条目命名Claude Desktop 在自己的进程中启动你的服务器所以 shell 里的环境变量并不存在。uv run mcp install server.py -v API_KEYabc123或-f .env会把它们写进配置条目的env字段。--name覆盖条目名称默认取服务器的name。源码层面update_claude_config会保留已有的 env 变量仅在提供新值时以新值优先合并见 src/mcp/cli/claude.py且--env-file需要python-dotenv支持见 src/mcp/cli/cli.py。Claude Code无需编辑文件一条 CLI 注册Claude Code 不需要编辑任何文件。用claudeCLI 注册服务器--之后的所有内容就是启动命令claude mcp add bookshop -- uv run --with mcp[cli] mcp run /absolute/path/to/server.py在 Claude Code 会话中执行/mcp确认bookshop已连接且其工具出现在列表中。Cursor项目根目录下的.cursor/mcp.json在项目根目录创建.cursor/mcp.json{ mcpServers: { bookshop: { command: uv, args: [run, --with, mcp[cli], mcp, run, /absolute/path/to/server.py] } } }同样的command加args置于与 Claude Desktop 相同的mcpServers键下。保存后服务器会出现在 Cursor 的 MCP 设置中两个工具都会列出。VS Code项目根目录下的.vscode/mcp.json在项目根目录创建.vscode/mcp.json{ servers: { bookshop: { type: stdio, command: uv, args: [run, --with, mcp[cli], mcp, run, /absolute/path/to/server.py] } } }与 Cursor 配置文件相比只有两处差异而且仅此两处包裹键是servers而非mcpServers每条目显式声明了type。确认信任提示后在命令面板执行MCP: List Servers会看到bookshop正在运行。注意需要 VS Code 1.99 或更高版本并已登录GitHub Copilot扩展Copilot Free 即可同时 Copilot Chat 必须处于Agent模式——只有该模式会调用工具。排查服务器不出现怎么办在动任何 host 配置之前先自己在终端跑一遍启动命令uv run --with mcp[cli] mcp run /absolute/path/to/server.py它什么都不打印、也不会退出——这种沉默才是正确的一个 stdio 服务器正等待 host 先通过 stdin 说话Ctrl-C停止。真正的问题是 traceback 或立即退出此时你能直接读到错误而不必隔着 host 猜。一旦这条命令停留在等待状态剩下的问题几乎总是下面三种之一相对路径。host 从它自己的工作目录启动你的服务器而不是你注册时的目录。该写/absolute/path/to/server.py的地方写了server.py是所有故障中最常见的一个。如果 host 连uv也找不到uv的路径同样必须是绝对的。host 仍在运行旧配置。host 在启动时读取配置。特别是 Claude Desktop编辑claude_desktop_config.json后必须彻底退出不是只关窗口再重新打开才能生效。有东西在转发的窗口之外写到了 stdout。在 stdio 上stdout 本身就是协议。SDK 会在服务期间把溢出的输出改写到 stderr但此前已 flush 到 stdout 的输出包装脚本的 echo、无缓冲进程在导入期的print()或者解释器退出时被冲刷的缓冲print()会把损坏的消息交给 host导致连接被断开。请使用默认logging配置记录日志——它的 stderr handler 会逐条刷新自定义 handler 也必须避开 stdout。日志 有完整的说明。Claude Desktop 为每个服务器保留一份日志mcp-server-NAME.log即你服务器的 stderr与记录连接的mcp.log相邻位于 macOS 的~/Library/Logs/Claude和 Windows 的%APPDATA%\Claude\logs。超出上述三种情况之外故障排查 是专门的页面。小结hostClaude Desktop、IDE 等运行着一个 MCP 客户端它通过 stdio 把你的服务器作为子进程启动。连接就是给它一条启动命令。这条命令是uv run --with mcp[cli] mcp run /absolute/path/to/server.py无需激活虚拟环境从任意目录都能运行。Claude Desktop是mcp install唯一能替你配置的 host。它把同一条命令外加uv绝对路径、--frozen、对已装版本的精确固定写入claude_desktop_config.json你永远不用手写。Claude Code是claude mcp add bookshop -- 启动命令Cursor是.cursor/mcp.json下的mcpServersVS Code是.vscode/mcp.json下的servers且每条目带type。处处使用绝对路径编辑配置后重启 host并且永远不要让 SDK 之外的任何东西写 stdout。本页所有 host 都用同一条命令连接到了同一个文件。这个文件还能暴露什么就是其余文档的主题工具、资源以及 stdio 之外的各种传输方式见 运行你的服务器。【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考