第一个本地stdio MCP看这篇就够了：从Python SDK创建到Cherry Studio调试再到Cursor集成

1. 为什么第一个 MCP 建议从本地 stdio 开始MCPModel Context Protocol这两年被讨论得很多但真正动手时很多人卡在第一步到底该用哪种传输方式远程 SSE、Streamable HTTP、还是本地 stdio如果你只是想先跑通一个能用的 MCP Server我的建议是直接从本地 stdio 入手。原因很直接stdio 不需要你暴露端口、不需要处理鉴权、不需要考虑网络连通性进程之间通过标准输入输出通信调试链路最短。stdio 的本质是「父进程启动子进程通过 stdin/stdout 交换 JSON-RPC 消息」。Cherry Studio、Cursor 这类客户端会以子进程方式拉起你的 Python 脚本然后把工具列表、调用请求写进 stdin你的脚本把结果写回 stdout。理解这一点后面所有配置报错你都能自己定位。这篇文章面向的是第一次写 MCP Server 的人。你会得到一个可复制的最小 server 骨架包含 Tool、Resource、Prompt 三类能力然后我会带你在 Cherry Studio 里完成可视化调试确认工具真的被模型调用了最后把同一份配置迁移到 Cursor在真实编码场景里验证。整个过程不需要你懂异步框架也不需要你部署任何服务。模型调用这一层我会用 TaoToken 统一管理 Key 和 API 通道这样你在 Cherry Studio 和 Cursor 里切换模型时不用反复改配置。下面从环境准备开始。2. 用 uv 初始化项目并安装 MCP Python SDK官方 Python SDK 推荐用 uv 管理依赖它比 pip 快虚拟环境和依赖锁定也更省心。先确认你本机有没有 uvuv --version如果没有输出Windows 下用 PowerShell 安装powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iexmacOS 或 Linux 用curl -LsSf https://astral.sh/uv/install.sh | sh装完再看一次版本然后确认 Python 版本列表uv python list如果没有合适的版本直接装一个比如uv python install 3.11接着新建项目目录并初始化。假设你放在桌面mkdir mcp-server cd mcp-server uv init . -p 3.11 uv add mcp[cli]这一步会生成pyproject.toml、.python-version和基础结构。uv add mcp[cli]会把 MCP SDK 和命令行工具一起装进虚拟环境。装完后目录里应该能看到main.py我们接下来就改它。注意uv init生成的main.py是示例代码直接覆盖即可不用保留。3. 编写最小 stdio MCP Server 骨架打开main.py把内容替换成下面这份完整代码。它同时演示了 Tool、Resource、Prompt 三种能力传输方式固定为 stdiofrom mcp.server.fastmcp import FastMCP mcp FastMCP(Demo, json_responseTrue) mcp.tool() def add(a: int, b: int) - int: Add two numbers return a b mcp.resource(greeting://{name}) def get_greeting(name: str) - str: Get a personalized greeting return fHello, {name}! mcp.prompt() def greet_user(name: str, style: str friendly) - str: Generate a greeting prompt styles { friendly: Please write a warm, friendly greeting, formal: Please write a formal, professional greeting, } return f{styles.get(style, styles[friendly])} for someone named {name}. if __name__ __main__: mcp.run(transportstdio)FastMCP是官方的高层封装用装饰器就能把普通函数注册成 MCP 能力。mcp.run(transportstdio)是关键它让进程通过标准输入输出通信而不是监听端口。如果你从官方示例复制代码注意把默认的streamable-http改成stdio否则客户端拉起进程后会连不上。三类能力的区别可以用 HTTP 类比记忆Tool 相当于 POST会产生操作或副作用比如加法、写文件、调外部接口Resource 相当于 GET只读地暴露数据比如配置、文档、动态生成的文本Prompt 是预定义的提示词模板用户选中后自动填充省去重复输入。函数名、参数名、类型注解和 docstring 都会暴露给模型。模型看到的是「有一个叫 add 的工具接收两个整数返回它们的和」。所以 docstring 别省它是模型判断何时调用你的主要依据。4. 在 Cherry Studio 中配置并调试 MCP先确认 server 能独立启动。在项目目录执行uv run main.py如果终端没有立刻报错退出说明进程正常挂起等待 stdio 输入按 CtrlC 结束即可。这一步能排除掉大部分「代码本身有问题」的情况。打开 Cherry Studio进入「设置 → MCP 服务器」选择添加类型选 stdio。命令和参数按下面填{ mcpServers: { demo-stdio: { command: uv, args: [ --directory, C:\\Users\\你的用户名\\Desktop\\mcp-server, run, main.py ] } } }--directory后面换成你自己的项目绝对路径Windows 路径里的反斜杠要写成双反斜杠。保存后如果配置正确Cherry Studio 会显示连接成功通常伴随一串进程或工具信息输出。接下来配置模型。在 Cherry Studio 的模型设置里填入 API Key 和接口地址。如果你用 TaoToken 统一管理可以在控制台创建 Key接口地址填https://taotoken.net/api模型名按你实际使用的填。这样 Cherry Studio 和后面的 Cursor 可以共用同一个 Key不用来回切换。配置完成后新建对话直接问「帮我算一下 123 加 456」。观察对话过程如果模型调用了add工具并返回 579说明 stdio 链路、工具注册、模型调用三件事全部打通。这一步是整个流程里最关键的验证点先在这里跑通再去 Cursor 会顺很多。5. 迁移到 Cursor 并验证工具调用Cursor 的 MCP 配置位置因版本而异常见的是用户级~/.cursor/mcp.json也有项目级的.cursor/mcp.json。最省事的做法是从 Cherry Studio 里复制已经验证过的 JSON粘贴到 Cursor 的配置文件里结构完全一致{ mcpServers: { demo-stdio: { command: uv, args: [ --directory, C:\\Users\\你的用户名\\Desktop\\mcp-server, run, main.py ] } } }保存后回到 Cursor 的 MCP 面板如果条目旁边亮起绿灯说明进程被成功拉起、工具列表读取正常。红灯通常是路径写错、uv 不在 PATH 里或者main.py里 transport 没改成 stdio。在 Cursor 里验证时可以直接在对话中说「用 add 工具算 88 加 12」也可以让它读取 Resource。比如问「读取 greeting://Cursor 的内容」模型应该返回Hello, Cursor!。Prompt 则可以在斜杠命令或提示词选择里看到greet_user选中后会自动填充模板。实际编码时你可以把项目相关的只读信息做成 Resource让模型按需读取把格式化、校验、调用内部脚本这类操作做成 Tool。这样模型在改代码前能先拿到上下文改完还能调用你的校验工具闭环会顺很多。6. 常见报错与排查清单配置 stdio MCP 时报错基本集中在几个地方。下面这张表可以对照排查现象常见原因处理方式客户端显示连接失败transport 仍是 streamable-http改成mcp.run(transportstdio)进程启动即退出依赖没装进当前环境在项目目录执行uv add mcp[cli]找不到 uv 命令uv 未加入 PATH重开终端或填 uv 的绝对路径工具列表为空装饰器函数有语法错误单独uv run main.py看报错路径相关报错--directory路径不对用绝对路径Windows 双反斜杠模型不调用工具docstring 缺失或描述模糊补全函数说明和参数含义还有一个容易忽略的点stdio server 的 stdout 只能输出 JSON-RPC 消息。如果你在代码里用print()调试输出会污染协议通道导致客户端解析失败。调试信息请写进 stderr或者用日志库输出到文件。如果 Cherry Studio 能连上但 Cursor 连不上优先检查两边用的路径是否一致。Cursor 有时以不同工作目录启动进程相对路径会失效所以统一用绝对路径最稳。7. 用 TaoToken 统一管理模型调用通道MCP Server 解决的是「模型能调用什么工具」而模型本身走哪条 API 通道是另一件事。当你在 Cherry Studio、Cursor、以及后续可能接入的 Coding Agent 里都用同一个模型时分散管理 Key 会很麻烦。TaoToken 的作用就是把 Key 和 API 通道统一起来。在控制台创建 API Key 后接口地址填https://taotoken.net/api把 Key 填进 Cherry Studio 或 Cursor 的模型配置即可。这样你换模型、加额度、排查调用问题都只在一个地方操作。如果你主要在 Cursor 里做长期编码可以了解下 Coding Plan如果只是想先验证模型对话是否正常用模型对话页面快速试一条请求就行。需要提醒的是MCP 的 stdio 通道和模型 API 通道是两条独立的链路。前者由客户端拉起本地进程后者是网络请求。排查问题时先分清是哪条链路出错工具没被调用看 MCP 配置模型没响应看 API Key 和接口地址。把这两条链路都跑通之后你就可以在这个骨架上继续加 Tool 了。比如封装一个调用内部 HTTP 接口的工具或者做一个动态返回文件列表的 Resource。骨架不变只加装饰器函数客户端重新连接就能看到新能力。