MCP 接入
插件解决「Bot 少什么功能」,MCP 解决「Bot 怎么用上外部工具」。这一页带你十分钟把 MCP server 接到 Bot 上。
MCP 配置有两条完全对等的改法:用编辑器改 config/mcp.toml,或者在 WebUI 的「MCP 配置」编辑器里点出来。两条路改的是同一份配置、覆盖同样的内容,只是操作方式不同。下面每一步都同时给出两种做法,任选一条跟着走即可;配置文件怎么改、怎么生效的通用规则见核心配置要点。
MCP 是什么?
大白话:MCP(Model Context Protocol,模型上下文协议)就是一个「万能插座」。USB 让各种外设插上电脑就能用,MCP 让各种外部工具插上 AI 就能用——本地文件、网页抓取、数据库、你自己写的服务……只要对方提供 MCP server,Bot 就能直接调用它的工具,不用为每个工具单独写插件。
MCP 是标准协议,社区里有大量现成 server,配置基本都能直接抄。
先弄懂:三类服务器
不管用哪种改法,MCP 服务都分成三类,各配各的,写在同一个文件里:
stdio_servers本地进程 —— Bot 在你电脑上拉起一个程序,通过标准输入输出和它通信。最常用,社区里大多数现成 server 都是这种。sse_servers远程 SSE —— 连一个远程服务给的 URL。streamable_http_servers远程 Streamable HTTP —— 也是连远程 URL,是比 SSE 更新的传输方式,服务方给哪种就用哪种。
每类服务还支持两个公共可选项:
| 字段 | 默认值 | 说明 |
|---|---|---|
instructions | 不填 | 给这个服务额外补充的系统指令,帮 Bot 更懂怎么用它 |
defer_loading | true | 延迟加载:开启时该服务的工具只对子代理暴露,不挤占主工具列表。发现某个工具没出现在 Bot 的主工具列表里,可以设为 false 试试 |
WebUI 的「MCP 配置」编辑器里,「Stdio 服务器 / SSE 服务器 / Streamable HTTP 服务器」三个标签页正好对应这三类,按需添加就行。
第一步:接一个本地工具(Stdio)
最常见的用法,比如官方的文件系统 server,让 Bot 能读写指定目录。
用编辑器打开 config/mcp.toml(没有这个文件时,Bot 首次启动会自动生成默认配置)。在 [mcp.stdio_servers] 下加一段,key 是你起的服务名,value 是它的配置:
| 字段 | 必填 | 说明 |
|---|---|---|
command | 必填 | 启动命令,比如 npx、uvx、python |
args | 参数列表 | |
env | 给这个进程额外注入的环境变量(比如 API key) | |
instructions / defer_loading | 公共可选项,见上表 |
Node.js 写的 server 用 npx 启动:
[mcp.stdio_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/yourname/mofox-files"]Python 写的 server 用 uvx 启动,比如官方的网页抓取 server:
[mcp.stdio_servers.fetch]
command = "uvx"
args = ["mcp-server-fetch"]需要注入环境变量(比如 API key)时加一个 env 小节:
[mcp.stdio_servers.my_server]
command = "npx"
args = ["-y", "some-mcp-server"]
[mcp.stdio_servers.my_server.env]
API_KEY = "sk-xxx"Bot 启动时会把这些进程拉起来,通过标准输入输出和它们通信。
第二步:接一个远程服务(SSE / Streamable HTTP)
远程服务直接给个 URL 就行。两类远程服务配法一样,只是写在不同的节里——服务方给的是 SSE 地址就配 sse_servers,给的是 Streamable HTTP 地址就配 streamable_http_servers。
以 SSE 为例,最简写法直接给 URL 字符串:
[mcp.sse_servers]
weather = "https://example.com/sse"需要带请求头或调整超时的话用表写法:
[mcp.sse_servers.weather]
url = "https://example.com/sse"
timeout = 10
[mcp.sse_servers.weather.headers]
Authorization = "Bearer sk-xxx"表写法的字段:
| 字段 | 默认值 | 说明 |
|---|---|---|
url | 必填 | 服务的地址 |
headers | 请求头,比如放鉴权 token | |
timeout | SSE 5 / Streamable HTTP 30 | 建立连接的超时(秒),网络差就调大 |
sse_read_timeout | 300 | 仅 SSE:读数据的超时(秒),一般不用动 |
instructions / defer_loading | 公共可选项,见上表 |
换成 Streamable HTTP 就是把节名换掉,字段一样:
[mcp.streamable_http_servers]
docs = "https://example.com/mcp"别重复定义
同一个服务名在文件里只能出现一次:上面「最简写法」和「表写法」是二选一,两种都写会导致配置解析报错「Cannot overwrite a value」。
改完怎么生效、怎么验证
先说生效,再说验证。
- WebUI 改的:点「保存」后 WebUI 默认会自动热重载 MCP 配置(设置里的「保存后自动热重载」默认开启),不用重启 Bot。改完没生效再重启一次。
- 手改文件的:保存
config/mcp.toml后重启 Bot 生效。
- 重启 Bot,打开
logs/目录下最新的日志文件,搜索mcp_manager。看到这两行就说明成了:text如果已连接 MCP 服务器: filesystem 已动态注册 MCP 工具: mcp_provider:tool:mcp-filesystem-list_directory[mcp]的enabled是false,日志会提示「MCP 功能未启用」——这个总开关平时不用动,默认就是true。

- 工具的命名规则是
mcp-<服务名>-<工具名>(统一转成短横线格式),比如服务名weather_server里的get_weather工具,就叫mcp-weather-server-get-weather。 - 在聊天里直接用:比如接了文件系统 server 后,对 Bot 说「帮我看看 /home/yourname/mofox-files 里有什么文件」,看它会不会调工具。
常见问题
提示 command not found(或测试按钮报「命令不存在」)
- 原因:
command指向的程序没装或不在 PATH 里。最常见的是npx没装——它随 Node.js 一起安装,先装 Node.js(建议 LTS 版)再重试。 - 解决:
- 终端里跑
node -v和npx -v确认能找到; - Windows 下如果
npx起不来,可以试着把command改成cmd、args前面加"/c"(如args = ["/c", "npx", "-y", ...]); - 用
uvx/python启动的 server,确认对应工具已安装且在 PATH 里。
- 终端里跑
连接超时
- 原因:远程服务不可达,或超时设得太短。
- 解决:
- 先用浏览器或
curl确认 URL 从你机器上能访问到; - SSE 默认只等 5 秒,网络差就把
timeout调大(Streamable HTTP 默认 30 秒); - 挂了代理的话,确认代理能通到目标地址(见下一条)。
- 先用浏览器或
环境变量与代理
- stdio 方式启动的 MCP 进程会继承 Bot 主程序的全部环境变量,
env字段是在此基础上的补充和覆盖; - 远程连接(SSE / Streamable HTTP)走 httpx,默认遵循系统代理环境变量(
HTTP_PROXY、HTTPS_PROXY等)——代理配置不对会直接连不上; - 模型请求、插件市场同步的系统代理行为由
core.toml里[advanced]的trust_env控制(详见 常见问题 FAQ)。
WebUI 里保存了但 Bot 没用上工具
- 确认点了右上角「保存」——有未保存改动时按钮才会亮;
- 检查「保存后自动热重载」是否被关掉了(WebUI 的「设置」页),关了的话保存后需要手动重启 Bot;
- 还不行就重启一次 Bot 再看日志——个别情况下运行中的组件握着旧配置引用,重启才彻底刷新。
配置好之后,Bot 的能力边界就取决于你能找到多少好用的 MCP server 了。装常规插件还是看插件市场使用;遇到问题去 常见问题 FAQ。
相关页面:
