【AI入门】CherryStudio入门3：结合FastMCP创建自己的MCP服务，实现哔哩视频查询

1. 从零理解 MCP 与 FastMCP为什么要在 CherryStudio 里自己造一个哔哩视频查询工具你可能已经在 CherryStudio 里用过别人配好的 MCP 服务器点几下就能让模型读文件、查数据库。但有没有想过这些工具到底是怎么被模型“看见”并调用的如果我想让模型帮我搜哔哩哔哩上的视频能不能自己写一个答案是能而且用 FastMCP 写一个可用的哔哩视频查询服务代码量比你想象中少得多。先把这个场景说清楚。假设你在写一篇关于“MCP 服务器构建”的技术文章需要快速找几个哔哩哔哩上的相关视频作为参考。手动打开浏览器、输入关键词、翻页、复制链接这一套下来至少几分钟。如果让 CherryStudio 里的模型直接调用一个“哔哩视频查询”工具你只需要在对话框里说“帮我搜一下 MCP 服务器构建相关的视频”模型就会自动调用你写的 MCP 服务把搜索结果拿回来甚至帮你整理成列表或网页。这就是 MCP 的价值把外部能力标准化地暴露给模型。MCP 全称 Model Context Protocol是 Anthropic 开源的一套协议核心目标是让 AI 模型能以统一的方式调用外部工具、读取资源和获取提示模板。它把整个交互拆成三个角色MCP 主机运行 AI 应用的环境比如 CherryStudio、MCP 客户端负责和服务器通信的中介、MCP 服务器真正提供工具能力的一方。通信方式支持标准输入输出stdio、SSE 和 Streamable HTTP本地开发最常用的就是 stdio因为不需要额外开端口CherryStudio 直接通过命令行启动你的 Python 脚本就能通信。那 FastMCP 又是什么你可以把它理解成 MCP 协议的“高级封装框架”。原生 MCP 协议需要你手动处理服务器初始化、协议解析、内容类型、错误管理这些底层细节写起来很啰嗦。FastMCP 用装饰器的方式把普通 Python 函数直接变成 MCP 工具你只需要关心“这个函数做什么”剩下的协议适配它全包了。比如你写一个general_search(keyword)函数加上mcp.tool()装饰器FastMCP 会自动把函数名作为工具名、文档字符串作为工具描述、参数类型注解生成输入 schema还会处理参数验证和错误报告。模型在 CherryStudio 里看到的工具列表就是这些被装饰的函数。这篇文章适合谁如果你刚接触 CherryStudio已经会安装和基本配置但还没自己写过 MCP 服务那这篇就是为你准备的。如果你已经用过别人配的 MCP想搞清楚背后的运行机制或者想把自己的 Python 脚本变成模型能调用的工具同样适用。我会从环境准备开始一步步带你写一个哔哩视频查询的 MCP 服务然后在 CherryStudio 里配置、启动、验证最后把请求 endpoint 切到 TaoToken 的统一通道让整个调用链路更可控。整个过程不需要你精通异步编程也不需要你理解 MCP 协议的每个字节跟着做就能跑通。有一点需要提前说明哔哩哔哩的搜索接口本身是公开的我们通过bilibili-api-python这个库来调用它封装了搜索、视频信息、用户信息等常用功能。你不需要申请任何 API Key 就能用搜索功能这降低了入门门槛。但如果你后续想接入更复杂的模型能力比如让模型对搜索结果做摘要或生成网页那就需要配置模型通道。这部分我会在第三节详细讲包括如何把请求指向 TaoToken 的 API 地址用统一 Key 管理调用。2. 环境准备与 FastMCP 安装uv 虚拟环境 bilibili-api-python 依赖配置在写代码之前先把环境搭好。我推荐用 uv 来管理 Python 虚拟环境和依赖原因是它比 pip 快很多而且能自动处理虚拟环境的创建和激活对新手友好。如果你还没装 uv可以先在命令行里执行pip install uv或者参考 uv 的官方文档安装。装好之后找一个你习惯的工作目录比如E:\00ven\fastmcphome在地址栏输入cmd或dos打开命令行窗口。第一步创建虚拟环境。命令是uv venv fastmcpv其中fastmcpv是环境名称你可以改成自己喜欢的。执行后 uv 会在当前目录下生成一个fastmcpv文件夹里面包含 Python 解释器和相关文件。接下来激活环境Windows 下执行.\fastmcpv\Scripts\activatemacOS 或 Linux 下执行source fastmcpv/bin/activate。激活后命令行提示符前面会出现环境名称表示你已经进入这个虚拟环境。如果你忘了激活uv 在执行安装命令时也会自动找到当前目录下的虚拟环境但显式激活能避免很多路径问题。第二步安装 FastMCP。在激活的环境里执行uv pip install fastmcp。这个命令会从 PyPI 下载 FastMCP 及其依赖包括 MCP 协议的核心库。安装完成后你可以运行fastmcp version来验证是否成功。如果输出了版本号说明 FastMCP 已经可用。这里有个小坑有些教程会让你用pip install fastmcp但如果你同时装了多个 Python 版本pip 可能装到全局环境而不是虚拟环境里导致 CherryStudio 启动时找不到模块。用 uv 的uv pip install能确保装到当前虚拟环境。第三步安装哔哩哔哩 API 库。我们用的是bilibili-api-python它提供了搜索、视频详情、弹幕等接口的 Python 封装。命令是uv pip install bilibili-api-python。这个库依赖requests和aiohttp等包uv 会自动处理。安装完成后你可以写一个简单的测试脚本验证from bilibili_api import search, sync result sync(search.search(MCP服务器)) print(result[result][0][title])如果输出了某个视频的标题说明库能正常工作。注意sync函数的作用是把异步的search.search包装成同步调用这样我们就不需要写async和await了。对于 MCP 工具来说同步函数更简单FastMCP 也支持同步函数注册为工具。第四步准备代码编辑器。我用的是 VS Code你也可以用 Trae 或其他你习惯的编辑器。打开虚拟环境目录按CtrlShiftP打开命令面板输入 “Python: Select Interpreter”选择fastmcpv环境下的 Python 解释器。这一步很重要因为编辑器需要知道用哪个 Python 来解析你的代码否则会出现导入报错。选好之后新建一个文件myMCPSvr.py我们接下来就在这个文件里写 MCP 服务。在写代码之前再确认一下目录结构。假设你的工作目录是E:\00ven\fastmcphome那么虚拟环境在E:\00ven\fastmcphome\fastmcpv你的脚本myMCPSvr.py可以放在E:\00ven\fastmcphome下也可以放在虚拟环境目录里。我建议放在工作目录下和虚拟环境平级这样路径清晰。后面在 CherryStudio 里配置命令时需要指定--directory参数指向虚拟环境目录让 uv 知道用哪个环境来运行脚本。还有一点关于网络请求的说明。bilibili-api-python在搜索时会向哔哩哔哩的公开接口发请求不需要登录或 Cookie。但如果你频繁请求可能会触发限流。对于个人使用和测试来说正常频率完全够用。如果你后续想接入模型能力比如让模型对搜索结果做摘要那就需要配置模型通道。这部分我会在第三节详细讲包括如何把请求指向 TaoToken 的 API 地址用统一 Key 管理调用。3. 编写 FastMCP 服务端代码注册哔哩视频查询工具并配置 stdio 传输现在开始写核心代码。打开myMCPSvr.py把下面的代码完整复制进去。我会逐段解释关键部分确保你理解每一行在做什么。from typing import Any from bilibili_api import search, sync from mcp.server.fastmcp import FastMCP mcp FastMCP(Bilibili mcp server) mcp.tool() def general_search(keyword: str) - dict[Any, Any]: 执行 Bilibili 的搜索并返回结果。 参数: keyword (str): 要搜索的关键词 返回: dict[Any, Any]: 包含搜索结果的字典数据 data sync(search.search(keyword)) return data if __name__ __main__: mcp.run(transportstdio)第一段导入三个东西typing.Any用于类型提示bilibili_api的search和sync用于搜索和异步转同步FastMCP用于创建服务器实例。FastMCP(Bilibili mcp server)创建了一个名为 “Bilibili mcp server” 的服务器这个名字会显示在 CherryStudio 的工具列表里方便识别。mcp.tool()装饰器是核心。它把下面的general_search函数注册为一个 MCP 工具。FastMCP 会自动做几件事用函数名general_search作为工具名称用文档字符串作为工具描述根据keyword: str生成输入 schema告诉模型这个工具需要一个字符串参数。模型在 CherryStudio 里看到的就是这些信息它会根据描述判断什么时候该调用这个工具。函数体只有两行sync(search.search(keyword))把异步搜索转成同步调用然后返回结果。search.search返回的是一个字典包含result列表每个元素有视频标题、作者、播放量、链接等信息。你可以直接返回整个字典模型会自己解析。如果你想让返回结果更精简也可以在这里做过滤比如只保留标题和链接mcp.tool() def general_search(keyword: str) - list[dict[str, str]]: 搜索 Bilibili 视频返回标题和链接列表。 参数: keyword (str): 搜索关键词 返回: list[dict[str, str]]: 包含标题和链接的列表 data sync(search.search(keyword)) results [] for item in data.get(result, [])[:10]: results.append({ title: item.get(title, ), url: fhttps://www.bilibili.com/video/{item.get(bvid, )} }) return results这样返回的数据更干净模型生成网页或列表时也更容易处理。你可以根据自己的需求调整返回字段。最后一行mcp.run(transportstdio)启动服务器使用标准输入输出通信。这是 CherryStudio 最常用的方式不需要开端口CherryStudio 会通过命令行启动这个脚本然后通过 stdin/stdout 和它交换 JSON 消息。注意if __name__ __main__:这个判断它确保脚本只在直接运行时启动服务器被导入时不会执行。写完之后在终端里测试一下。激活虚拟环境运行fastmcp run myMCPSvr.py。如果一切正常你会看到服务器启动的日志没有报错就说明代码没问题。你也可以用fastmcp dev myMCPSvr.py启动调试模式它会打开一个 Web 界面让你手动调用工具、查看输入输出。首次运行fastmcp dev会安装一些额外的调试依赖稍等片刻即可。在浏览器里访问提示的端口通常是 6274点击 “Connect”选择general_search工具输入关键词 “MCP服务器”点击执行就能看到搜索结果。这个调试工具非常有用可以在接入 CherryStudio 之前先验证服务本身是否正常。如果你在运行fastmcp run时遇到ModuleNotFoundError: No module named mcp说明 FastMCP 没装到当前环境重新执行uv pip install fastmcp。如果遇到ModuleNotFoundError: No module named bilibili_api同样用uv pip install bilibili-api-python安装。如果搜索时返回空结果或报网络错误检查一下网络连接哔哩哔哩的公开接口在国内可以直接访问。4. 在 CherryStudio 中接入 MCP 服务stdio 配置与一次真实查询验证代码跑通之后接下来把它接入 CherryStudio。打开 CherryStudio点击左下角的“设置”找到“MCP 服务器”选项点击“添加服务器”。在弹出的窗口里填写以下信息名称mybilibili你可以取任何好记的名字 类型选择“标准输入输出stdio” 命令uv参数--directory E:\00ven\fastmcphome\fastmcpv run myMCPSvr.py这里的参数需要根据你的实际路径调整。--directory指向你的虚拟环境目录run myMCPSvr.py告诉 uv 在这个环境里运行脚本。命令和参数合起来等价于你在终端里执行的uv --directory E:\00ven\fastmcphome\fastmcpv run myMCPSvr.py。如果你之前在终端里测试通过这里直接复制过来就行。填完之后点击“保存”然后点击服务器右侧的启动按钮。按钮变绿表示启动成功。如果变红或一直转圈说明启动失败常见原因有几个路径写错了、uv 不在系统 PATH 里、虚拟环境里没装 fastmcp 或 bilibili-api-python。你可以先在终端里手动执行一遍命令确认能正常启动再回到 CherryStudio 里检查配置。启动成功后进入一个助手对话在输入框上方找到 MCP 服务器图标点击后勾选mybilibili。然后输入问题“搜索 MCP 服务器构建的相关视频并生成一个网页。”模型会先分析你的需求判断需要调用general_search工具然后自动发起调用。你会在对话里看到工具调用的过程包括传入的参数keyword: MCP服务器构建和返回的结果。模型拿到结果后会根据你的要求生成一个网页把视频标题和链接展示出来。点击工具调用结果可以查看 MCP 返回的原始 JSON 数据。如果返回的result列表里有视频信息说明整个链路是通的。如果返回空列表可能是关键词太窄换个宽泛点的词试试。如果模型没有调用工具而是直接回答说明它没识别到需要调用 MCP你可以在对话里明确说“请使用 mybilibili 工具搜索”或者在助手设置里把 MCP 工具的描述写得更清楚。这里有一个实际经验模型生成的网页可能样式很简陋甚至有些 HTML 错误。这不是 MCP 的问题而是模型在生成代码时的能力边界。你可以让模型“优化页面样式”或“修复 HTML 错误”它会根据你的反馈调整。MCP 负责的是“把数据拿回来”至于怎么展示那是模型和你的交互问题。如果你想让整个调用链路更可控比如统一管理模型调用的 Key、切换不同的模型通道可以把请求 endpoint 指向 TaoToken 的 API 地址。具体做法是在 CherryStudio 的模型设置里把 API 地址改为https://taotoken.net/api然后填入你在 TaoToken 控制台创建的 API Key。这样模型调用和 MCP 工具调用就分开了MCP 工具负责搜索哔哩哔哩模型负责理解和生成两者通过 CherryStudio 协调。TaoToken 的统一 Key 管理能让你在不同模型之间切换时不用反复改配置对于长期做 AI 应用开发的人来说省事不少。5. 常见报错与排查401、local proxy failed、reading choices、OAuth 问题对照接入过程中最容易遇到的几个报错我在这里集中列一下方便你对照排查。401 Unauthorized这个报错通常出现在模型调用环节不是 MCP 本身的问题。如果你在 CherryStudio 里配置了模型 API但 Key 填错了或过期了模型请求会返回 401。检查一下 API Key 是否复制完整有没有多余空格。如果你用的是 TaoToken 的通道确认 Key 是在控制台创建的并且有对应模型的权限。MCP 工具调用不涉及 401因为哔哩哔哩搜索是公开接口。local proxy failed这个报错说明 CherryStudio 尝试通过本地代理连接 MCP 服务器但代理没启动或端口不对。如果你用的是 stdio 类型不应该出现这个报错因为 stdio 不走网络代理。检查一下 MCP 服务器类型是否选成了 SSE 或 HTTP如果是改回 stdio。另外如果你系统里设置了全局代理可能会干扰 uv 启动子进程尝试在 CherryStudio 设置里关闭代理或者把127.0.0.1加入代理例外。reading choices 相关报错这个通常出现在模型返回格式不符合预期时。比如你让模型生成 JSON但它返回了带 markdown 代码块的文本解析就会失败。解决方法是调整提示词明确要求“只返回 JSON不要加代码块标记”。如果你用的是 OpenAI 兼容接口检查response_format参数是否设置正确。MCP 工具返回的数据是标准 JSON不会出现这个问题问题一般出在模型生成环节。OAuth 相关报错如果你接入的 MCP 服务器需要 OAuth 认证比如某些云服务但没配置 token会报 OAuth 错误。我们写的哔哩哔哩搜索服务不需要 OAuth所以不会遇到。如果你后续接入其他需要认证的服务确保在 MCP 服务器配置里填入了正确的 token 或 client credentials。CherryStudio 的 MCP 配置界面支持自定义环境变量你可以把 token 作为环境变量传给服务器进程。工具调用成功但返回空结果检查关键词是否太具体或者哔哩哔哩接口是否临时限流。可以在终端里直接运行python -c from bilibili_api import search, sync; print(sync(search.search(测试)))看看有没有返回。如果终端里能返回但 CherryStudio 里不行检查 MCP 服务器启动日志看是否有异常输出。CherryStudio 启动 MCP 服务器失败最常见的原因是路径问题。--directory参数指向的目录必须存在且包含虚拟环境。如果你把虚拟环境建在E:\00ven\fastmcphome\fastmcpv但脚本放在E:\00ven\fastmcphome\myMCPSvr.py那么--directory应该指向E:\00ven\fastmcphome\fastmcpvrun后面的脚本路径可以是相对路径或绝对路径。建议用绝对路径避免歧义。另外uv 必须在系统 PATH 里CherryStudio 才能调用到它。你可以在终端里执行where uvWindows或which uvmacOS/Linux确认。如果你在配置过程中遇到其他报错可以先在终端里手动运行 MCP 服务器命令看完整错误输出。CherryStudio 的日志窗口也会显示服务器启动的 stderr那里通常有更详细的错误信息。把错误信息复制出来搜索大部分问题都能找到答案。6. 从搜索到生成把 MCP 工具接入 TaoToken 统一通道的完整链路到这里你已经完成了一个可用的哔哩视频查询 MCP 服务并且在 CherryStudio 里验证了调用。但如果你想把这条链路用到实际项目里比如批量搜索视频、自动生成报告、或者集成到自己的 Agent 工作流里还需要考虑模型通道的管理。这就是 TaoToken 发挥作用的地方。TaoToken 提供统一的 API 入口你可以用同一个 Key 调用不同的模型不需要为每个模型单独配置地址和密钥。在 CherryStudio 里进入“设置”-“模型服务”把 API 地址改为https://taotoken.net/api然后填入你在 TaoToken 控制台创建的 API Key。模型 ID 根据你需要的模型填写比如claude-sonnet-4-20250514或gpt-4o。配置完成后CherryStudio 的模型调用就会走 TaoToken 的通道而 MCP 工具调用仍然走本地 stdio两者互不干扰。这样做的好处是当你需要切换模型时只需要在 TaoToken 控制台调整不需要改 CherryStudio 的配置。对于长期做 AI 应用开发的人来说统一 Key 管理能省去很多重复配置的麻烦。另外TaoToken 的 API 兼容 OpenAI 格式如果你之前用 OpenAI SDK 写的代码只需要改base_url和api_key就能迁移过来。如果你想把 MCP 服务部署到远程让多个 CherryStudio 实例共用可以把transportstdio改成transportsse或transportstreamable-http然后指定端口。FastMCP 支持这三种传输方式改一行代码就行。不过对于个人使用来说stdio 最简单不需要处理端口和防火墙。最后说一个实用技巧你可以把多个工具注册到同一个 FastMCP 实例里比如再加一个get_video_info(bvid)工具根据视频 ID 获取详情。模型在 CherryStudio 里会看到两个工具根据你的问题自动选择调用哪个。工具越多模型能做的事情越多但也要注意描述写清楚避免模型混淆。FastMCP 的装饰器模式让扩展变得很简单你只需要写一个新函数加上mcp.tool()重启服务器就能用。整个流程走下来你会发现 MCP 并没有那么神秘。它本质上就是一个标准化的“函数调用协议”FastMCP 把协议细节封装好了你只需要写业务逻辑。CherryStudio 作为主机负责把模型和 MCP 服务器连接起来。TaoToken 作为模型通道负责处理模型调用。三者各司其职组合起来就能做出很实用的 AI 工具。如果你还没试过自己写 MCP 服务现在就可以打开编辑器从那个general_search函数开始。