MCP server 学习+案例实践：用 FastMCP 搭建本地 STDIO 小红书发送笔记 MCP 并改到 TaoToken

1. 从零理解 MCP server：本地 STDIO 到底解决了什么问题

MCP server 这个词最近出现频率很高，但很多人第一次接触时并不清楚它和普通 API 封装有什么区别。简单说，MCP（Model Context Protocol）是一套让大语言模型调用外部工具的标准化协议，你可以把它理解成 AI 世界的 USB 接口：只要工具按这个协议暴露能力，任何支持 MCP 的客户端都能直接调用，不需要为每个模型单独写适配层。MCP server 就是这套协议的服务端实现，负责把「发小红书笔记」这类具体动作包装成模型能识别的 tool。

我这次要做的场景很具体：用 FastMCP 搭一个本地 STDIO 模式的小红书发送笔记 MCP server，让 AI 客户端通过标准输入输出调用它，完成登录、发图文笔记、发视频笔记三个动作。STDIO 模式的特点是零网络开销、进程间直接通信，适合本地开发和单机工具链。整个链路里，MCP server 负责操作小红书，AI 客户端负责理解用户意图并决定调用哪个 tool，两者通过 STDIO 交换 JSON-RPC 消息。

为什么选 FastMCP？因为它是 Python 生态里上手成本最低的 MCP 服务端框架，一个装饰器就能把普通函数注册成 tool，参数类型和 docstring 会自动转成模型可读的工具描述。你不需要手写 JSON Schema，也不需要处理协议握手细节。对于「MCP server 入门 + 本地 STDIO 实战」这个目标来说，FastMCP 是最短路径。

这篇内容适合三类人：刚听说 MCP 想动手跑通一个完整案例的开发者；手里有本地自动化脚本、想把它暴露给 AI 客户端调用的工具作者；以及想把模型 endpoint 统一到 TaoToken 通道、避免多 Key 管理的团队。读完之后你应该能独立完成：写一个 FastMCP 服务端、用 STDIO 启动、在客户端里看到 tool 列表、调用发笔记工具、并把模型请求改到统一 API 通道验证连通性。

需要提前说明的是，小红书发送笔记涉及账号登录态，本文的 XiaohongshuPoster 是一个本地封装类，负责浏览器自动化和发布动作，你需要自己准备可用的登录环境。MCP server 本身只做工具暴露和参数转发，不处理账号风控，这部分请遵守平台规则，控制发布频率，不要用于批量灌水。

2. TaoToken 前置准备：统一 Key 与 API 通道怎么配

在写 MCP server 之前，先把模型调用通道准备好。原因是 MCP server 只负责工具执行，真正决定「AI 要不要调用发笔记工具」的是模型本身。如果你用多个模型供应商，每个都要配 Key、改 Base URL，调试时很容易混乱。TaoToken 的作用是把模型调用收敛到一个统一入口，你只需要一个 Key 和一套 Base URL，就能在 Claude Code、Cline、Codex 这类客户端里切换模型。

先拿到 API Key。打开 https://taotoken.net/api-keys ，登录后创建一个新 Key，复制保存。注意 Key 只在创建时完整显示一次，丢了就重新生成。这个 Key 后面会同时用在 MCP 客户端的模型配置和连通性验证里。

Base URL 统一用 https://taotoken.net/api ，不要加任何路径后缀。很多 401 报错都是因为把 Base URL 写成了带/v1/chat/completions的完整地址，客户端会再拼一次路径导致重复。记住原则：Base URL 只到/api，具体 endpoint 由客户端自己拼。

模型 ID 按你实际要用的填。比如做编码 Agent 常用 claude-sonnet 系列，做轻量工具调用可以用更小的模型。Model ID 必须和 TaoToken 控制台里列出的名称完全一致，大小写敏感。如果你不确定当前有哪些可用模型，直接打开 https://taotoken.net/console 查看模型列表，或者在 https://taotoken.net/models 里对照。

如果你用的是 Claude Code 这类需要 Anthropic 兼容格式的客户端，配置入口在 https://taotoken.net/claude-code-anthropic ，里面会给出对应的环境变量写法。核心就是三件套：Base URL 填https://taotoken.net/api，Key 填你刚创建的，Model ID 填控制台里的名称。这三项在后面的 settings 片段里会反复出现，先记牢。

对于长期跑编码任务或 Agent 的场景，建议直接看 Coding Plan： https://taotoken.net/coding-plan 。它适合需要持续调用、频繁切换模型的用法，比每次单独配 Key 更省事。如果你只是临时验证 MCP 工具调用，用按量 Key 就够了。

这里要强调一个容易踩的坑：MCP server 的 STDIO 通道和模型 API 通道是两条独立的链路。STDIO 负责客户端和本地 MCP server 之间的工具调用，TaoToken 负责客户端和模型之间的推理请求。两者不要混在一起配。你可以在 MCP 客户端里同时配置「模型走 TaoToken」和「工具走本地 STDIO server」，它们互不干扰。

3. 可复制配置：FastMCP 服务端与 STDIO 启动

这一节给出可以直接复制的代码和配置。先建目录结构，建议这样组织：

xhs_mcp_server/ ├── __init__.py ├── server.py ├── write_xiaohongshu.py └── requirements.txt

requirements.txt内容：

mcp requests

安装依赖：

pip install -r requirements.txt

核心服务端server.py，这是 FastMCP 注册 tool 的地方：

import os import concurrent.futures import requests from mcp.server import FastMCP from mcp.types import TextContent from .write_xiaohongshu import XiaohongshuPoster mcp = FastMCP("xhs") phone = os.getenv("phone", "") json_path = os.getenv("json_path", "/Users/Mi/") slow_mode = os.getenv("slow_mode", "False").lower() == "true" def download_images_parallel(urls: list) -> list: """并行下载图片或视频到本地临时目录""" local_paths = [] def _download(url): resp = requests.get(url, timeout=30) resp.raise_for_status() filename = os.path.join(json_path, url.split("/")[-1]) with open(filename, "wb") as f: f.write(resp.content) return filename with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool: for path in pool.map(_download, urls): local_paths.append(path) return local_paths @mcp.tool() def create_note(title: str, content: str, images: list) -> list[TextContent]: """Create a note (post) to xiaohongshu (rednote) with title, description, and images Args: title: the title of the note (post), which should not exceed 20 words content: the description of the note (post). images: the list of image paths or URLs to be included in the note (post) """ poster = XiaohongshuPoster(json_path) res = "" try: if len(images) > 0 and images[0].startswith("http"): local_images = download_images_parallel(images) else: local_images = images code, info = poster.login_to_publish(title, content, local_images, slow_mode) poster.close() res = info except Exception as e: res = "error:" + str(e) return [TextContent(type="text", text=res)] @mcp.tool() def create_video_note(title: str, content: str, videos: list) -> list[TextContent]: """Create a note (post) to xiaohongshu (rednote) with title, description, and videos Args: title: the title of the note (post), which should not exceed 20 words content: the description of the note (post). videos: the list of video paths or URLs to be included in the note (post) """ poster = XiaohongshuPoster(json_path) res = "" try: if len(videos) > 0 and videos[0].startswith("http"): local_videos = download_images_parallel(videos) else: local_videos = videos code, info = poster.login_to_publish_video(title, content, local_videos, slow_mode) poster.close() res = info except Exception as e: res = "error:" + str(e) return [TextContent(type="text", text=res)] def main(): mcp.run() if __name__ == "__main__": main()

write_xiaohongshu.py是发布动作的封装，你需要根据自己的浏览器自动化方案实现XiaohongshuPoster类，至少包含login_to_publish、login_to_publish_video、close三个方法。这里不展开具体实现，因为它依赖你的登录态和页面结构，重点是 MCP 层的接口设计。

STDIO 启动命令，用官方 inspector 调试：

npx @modelcontextprotocol/inspector -e phone=your_phone -e json_path=/Users/Mi/ python -m xhs_mcp_server

如果你在 MCP 客户端里配置，JSON 片段如下（以 Cline 的 MCP 配置为例）：

{ "mcpServers": { "xhs": { "command": "python", "args": ["-m", "xhs_mcp_server"], "env": { "phone": "your_phone", "json_path": "/Users/Mi/", "slow_mode": "True" } } } }

模型侧的三件套配置，以 settings 形式给出：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoTokenKey", "model": "claude-sonnet-4-20250514" }

注意base_url只写到/api，model必须和控制台一致。如果你用 Codex 的auth.json，结构类似：

{ "openai": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoTokenKey" } }

4. 验证请求：从 tool 列表到成功发笔记

配置写完后，第一步是确认 MCP server 能被客户端识别。用 inspector 启动后，浏览器会打开调试界面，左侧能看到xhsserver 的连接状态。如果显示 connected，点开 Tools 标签，应该能看到create_note和create_video_note两个工具，参数 schema 会自动从类型注解和 docstring 生成。

如果工具列表为空，先检查@mcp.tool()装饰器是否加在函数上，再确认mcp.run()被调用。FastMCP 默认走 STDIO，不需要额外指定 transport。

第二步是单独调用create_note验证发布链路。在 inspector 里填入：

{ "title": "MCP server 实战测试", "content": "这是通过 FastMCP 本地 STDIO 调用发布的笔记", "images": ["/Users/Mi/test.jpg"] }

点击 Run，观察返回。成功时返回的是发布结果信息，失败时返回error:开头的字符串。如果返回error:...，先看错误内容，常见的是登录态失效或图片路径不存在。

第三步是验证模型侧连通性。打开 https://taotoken.net/models 的对话入口，或者在你配置好的客户端里发一条消息，确认模型能正常响应。这一步和 MCP 工具调用是分开的，目的是确认 TaoToken 通道本身可用。如果模型对话正常，但 MCP 工具调用失败，问题一定在本地 server 或客户端配置，不在 API 通道。

第四步是端到端验证：在支持 MCP 的客户端里，让模型「帮我发一条小红书笔记，标题是测试，内容是 hello，图片用 /Users/Mi/test.jpg」。模型应该会调用create_note，客户端把参数通过 STDIO 传给本地 server，server 执行发布并返回结果。整个过程你能在客户端日志里看到 tool call 的请求和响应。

实测下来，STDIO 模式的响应速度很快，因为不经过网络。真正的耗时在浏览器自动化和图片上传，这部分取决于你的网络和页面加载速度。slow_mode设为 True 时会在操作间加延迟，降低被风控的概率，调试阶段建议开着。

5. 常见报错排查：401、local proxy failed、reading choices

这一节对照真实报错给出排查路径。第一个高频错误是 401 Unauthorized。如果你在模型调用时看到 401，先检查三件事：Key 是否复制完整、Base URL 是否只写到https://taotoken.net/api、Model ID 是否和控制台一致。三者任一不对都会 401。特别注意不要把 Base URL 写成带/v1的地址，客户端会重复拼接。

第二个错误是local proxy failed或连接被拒绝。这通常出现在 MCP 客户端启动本地 server 时。检查command和args是否能手动跑通：先在终端执行python -m xhs_mcp_server，如果报模块找不到，说明工作目录或包路径不对。MCP 客户端启动子进程时的工作目录可能和你终端不同，建议用绝对路径或在env里设置PYTHONPATH。

第三个错误是reading choices相关报错，通常出现在模型返回格式不符合预期时。如果你用的是兼容 OpenAI 格式的客户端，确认请求走的是 chat completions 而不是 responses 接口。TaoToken 的/api入口兼容主流格式，但客户端如果配错了 endpoint 类型，就会解析失败。检查客户端里的 API 类型设置，选 OpenAI Compatible 或 Anthropic Compatible，按你实际用的模型来。

第四个错误是 OAuth 相关报错。Claude Code 这类客户端有时会尝试 OAuth 流程，如果你用的是 API Key 模式，需要在配置里明确关闭 OAuth 或选择 API Key 认证。参考 https://taotoken.net/claude-code-anthropic 里的说明，把认证方式改成 Key。

第五个错误是工具调用返回error:但模型侧正常。这说明 MCP 链路通了，问题在发布动作本身。常见原因：登录态过期、图片路径不存在、标题超过 20 字、json_path目录没有写权限。逐个排查，先手动调用XiaohongshuPoster确认发布逻辑本身可用。

排查时建议打开客户端日志，看 STDIO 的原始 JSON-RPC 消息。FastMCP 的报错会带 traceback，定位到具体行。如果日志里看不到 tool call，说明模型没有决定调用工具，检查 tool 的 docstring 是否清晰描述了用途和参数。

6. 把 endpoint 改到 TaoToken 后的长期用法

MCP server 跑通之后，日常使用就是把模型 endpoint 固定在 TaoToken 通道。这样做的好处是：换模型不用改 MCP 配置，只改 Model ID；Key 统一管理，不用在每个客户端里重复填；调试时能在一个控制台看到调用情况。

如果你要长期跑编码或 Agent 任务，建议用 Coding Plan： https://taotoken.net/coding-plan 。它适合高频调用场景，配合本地 MCP server 做自动化工作流很顺。日常临时验证模型响应，直接用模型对话入口： https://taotoken.net/models 。需要管理多个 Key 或查看用量，去控制台： https://taotoken.net/console 。接入文档在 https://taotoken.net/doc ，遇到配置问题先翻文档。

最后给一个实用技巧：把 MCP server 的启动命令写成一个 shell 脚本，客户端配置里直接调脚本，这样环境变量和路径都集中在脚本里，换机器时只改一处。脚本里 export 好phone、json_path、slow_mode，再 exec python 模块。这样即使客户端的工作目录变化，也不会影响 server 启动。