MCP 配置
MCP（Model Context Protocol）让 MaiBot 能够连接外部工具，从"只会聊天"变成"又能说又能做"——查天气、搜新闻、读文件、调 API，全都可以。配置全部写在 bot_config.toml 的 [mcp] 段落下，下面按「总开关 → 客户端能力 → 服务器列表」依次展开。
在 WebUI 里管理 MCP 服务
MCP 服务的可视化入口在 插件扩展 页：侧边栏「扩展集成 → 插件扩展」，插件列表上方多出一节 MCP 服务（Sky 蓝圆点 + 服务数量），点任意服务或右上角的「管理服务」进入 MCP 设置。
- 每个服务一行，显示名称、传输方式、连接状态（已连接 / 未连接 / 连接异常 / 已禁用）、工具数，状态每 5 秒刷新一次
- 顶部可按名称、传输方式搜索；没有服务时提示「尚未添加 MCP 服务，点击『管理服务』连接更多工具」
- 在 MCP 设置页左上角点「返回插件扩展」回到插件列表，有未保存改动时会先确认
- 1.3.1 之前的侧边栏 MCP 设置 独立入口已移除，旧地址
/mcp-settings会跳转到插件扩展页；在「适配器设置」路径下不显示 MCP 服务分组 - MCP 服务列表的说明文案是「连接本地或远程工具服务，保存后即可供麦麦调用」
页面改的是同一份 [mcp] 配置，字段含义见下文；保存后会自动重建 MCP 连接，不需要重启。
配置结构总览
MCP 配置位于 bot_config.toml 的 [mcp] 段落下，分为三个层级：
[mcp]
enable = true # 总开关
[mcp.client] # 客户端宿主能力
client_name = "MaiBot"
client_version = "1.0.0"
[mcp.client.roots] # Roots 能力（向服务端暴露本地路径）
enable = false
[mcp.client.sampling] # Sampling 能力（允许服务端调用你的模型）
enable = false
task_name = "planner"
[mcp.client.elicitation] # Elicitation 能力（允许服务端请求用户填表）
enable = false
allow_form = true
allow_url = false
[[mcp.servers]] # MCP 服务器列表（可多个）
name = "my-server"
enabled = true
transport = "stdio"
command = "uvx"
args = ["some-mcp-server"]
env = { }
url = ""
headers = { }
http_timeout_seconds = 30.0
read_timeout_seconds = 300.0
[mcp.servers.authorization]
mode = "none"
bearer_token = ""总开关
enable— 是否启用 MCP，设为false时所有 MCP 服务器都不会连接。默认开启
客户端能力
这部分配置 MaiBot 作为 MCP 客户端时，向服务端声明自己的能力。
基础信息
[mcp.client]
client_name = "MaiBot"
client_version = "1.0.0"一般不需要改，除非你希望 MCP 服务端看到不同的客户端标识。
client_name— 客户端实现名称。默认"MaiBot"client_version— 客户端实现版本。默认"1.0.0"
Roots 能力
Roots 允许你向 MCP 服务器暴露本地文件系统路径，让服务器能读写这些路径下的文件。
[mcp.client.roots]
enable = true
[[mcp.client.roots.items]]
enabled = true
uri = "file:///home/mai/data"
name = "麦麦的数据目录"enable— 是否向 MCP 服务器暴露 Roots 能力。默认关闭items— Roots 列表。默认为空
每个 Root 项：
enabled— 是否启用。默认开启uri— Root URI，通常为file://路径，启用时必填。默认为空name— 显示名称。默认为空
💡 Roots 有什么用？
如果连接了一个文件系统 MCP 服务器（如 @modelcontextprotocol/server-filesystem），开启 Roots 后，服务器就能知道你的数据目录在哪，从而读写该目录下的文件。
Sampling 能力
Sampling 允许 MCP 服务端反过来请求 MaiBot 调用大模型来完成某些任务。这是一个高级的双向能力。
[mcp.client.sampling]
enable = true
task_name = "planner"
include_context_support = false
tool_support = trueenable— 是否启用 Sampling 能力声明。默认关闭task_name— 执行 Sampling 请求时使用的主程序模型任务名。默认"planner"include_context_support— 是否声明支持includeContext非none语义。默认关闭tool_support— 是否声明支持在 Sampling 中继续使用工具。默认关闭
⚠️ Sampling 会消耗 Tokens
启用 Sampling 意味着 MCP 服务端可以触发 MaiBot 的模型调用，会产生额外的 API 费用。确保 task_name 指向一个已配置好的模型任务。
Elicitation 能力
Elicitation 允许 MCP 服务端请求用户填写表单或在浏览器中打开 URL。
[mcp.client.elicitation]
enable = true
allow_form = true
allow_url = falseenable— 是否启用 Elicitation 能力声明。默认关闭allow_form— 是否允许表单模式 Elicitation。默认开启allow_url— 是否允许 URL 模式 Elicitation。默认关闭
启用时至少需要允许一种模式（allow_form 或 allow_url）。
服务器配置
这是最常用的部分——配置你想连接的 MCP 服务器。可以配置多个，每段 [[mcp.servers]] 对应一个服务器。
通用字段
[[mcp.servers]]
name = "playwright"
enabled = true
transport = "stdio" # 或 "streamable_http"、"sse"
http_timeout_seconds = 30.0
read_timeout_seconds = 300.0name— 必填。服务器名称，在同一配置中不能重复。默认为空enabled— 是否启用当前服务器。默认开启transport— 传输方式，"stdio"（默认）、"streamable_http"、"sse"http_timeout_seconds— HTTP 请求超时（秒）。默认 30.0read_timeout_seconds— 会话读取超时（秒）。默认 300.0
stdio 模式
通过启动一个本地子进程来运行 MCP 服务器，适合本地安装的工具。关键字段：
command— 启动命令，如uvx、npx、pythonargs— 命令参数列表env— 附加环境变量
通过 uvx 运行（推荐）
uvx 是 uv 自带的运行工具，自动管理依赖：
[[mcp.servers]]
name = "playwright"
transport = "stdio"
command = "uvx"
args = ["@playwright/mcp"][[mcp.servers]]
name = "mcp-sse"
transport = "stdio"
command = "uvx"
args = ["mcp-sse-server", "--port", "8080"]通过 npx 运行
需要先安装 Node.js：
[[mcp.servers]]
name = "github"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_your_token_here" }[[mcp.servers]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]通过 Python 运行
[[mcp.servers]]
name = "my-python-mcp"
transport = "stdio"
command = "python"
args = ["-m", "my_mcp_server"]
env = { PYTHONUNBUFFERED = "1" }streamable_http 模式
连接远程 MCP 服务（HTTP 端点），适合云服务或别人部署好的工具。关键字段：
url— MCP 端点地址，必填headers— 附加 HTTP 请求头authorization— HTTP 认证配置
无认证的远程服务
[[mcp.servers]]
name = "public-weather-mcp"
transport = "streamable_http"
url = "https://mcp.example.com/weather"
[mcp.servers.authorization]
mode = "none"带 Bearer Token 的远程服务
[[mcp.servers]]
name = "private-api-mcp"
transport = "streamable_http"
url = "https://api.example.com/mcp"
headers = { "X-Custom-Header" = "custom-value" }
[mcp.servers.authorization]
mode = "bearer"
bearer_token = "sk-your-bearer-token"带自定义请求头的远程服务
[[mcp.servers]]
name = "enterprise-mcp"
transport = "streamable_http"
url = "https://internal.example.com/mcp/v1"
headers = {
"X-API-Key" = "your-api-key",
"X-Tenant-ID" = "tenant-001",
}完整示例
基础配置：只连接一个服务
[mcp]
enable = true
[[mcp.servers]]
name = "playwright"
transport = "stdio"
command = "uvx"
args = ["@playwright/mcp"]这是最简单的配置——只写了一行 enable = true 加一个服务，其余全部走默认值。
日常使用配置：两个服务 + 基础能力
[mcp]
enable = true
[mcp.client]
client_name = "MaiBot"
client_version = "1.0.0"
# 连接 Playwright（浏览器自动化）
[[mcp.servers]]
name = "playwright"
transport = "stdio"
command = "uvx"
args = ["@playwright/mcp"]
# 连接文件系统服务器
[[mcp.servers]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]高级配置：启用 Sampling + Roots
[mcp]
enable = true
[mcp.client]
client_name = "MaiBot"
client_version = "1.0.0"
[mcp.client.roots]
enable = true
[[mcp.client.roots.items]]
enabled = true
uri = "file:///home/mai/data"
name = "数据目录"
[mcp.client.sampling]
enable = true
task_name = "planner"
tool_support = true
# 本地服务
[[mcp.servers]]
name = "playwright"
transport = "stdio"
command = "uvx"
args = ["@playwright/mcp"]
# 远程服务
[[mcp.servers]]
name = "weather-api"
transport = "streamable_http"
url = "https://mcp.example.com/weather"工具命名与冲突
麦麦把 MCP 提供的工具按原名交给模型，不加服务器前缀——filesystem 服务里的 read_file 就叫 read_file。同名冲突按三层规则处理，任何一层挡下都只记一条日志，不会报错：
- 内置保留名 — 与麦麦自带工具同名的直接跳过，保留名有
reply、no_action、stop、create_table、list_tables、view_table - 服务之间 — 多个服务提供同名工具时，按配置里的先后顺序，先配的生效，后来的跳过
- 与插件工具重名 — 最终汇总按「内置工具 → 插件工具 → MCP 工具」去重，同名时插件工具生效，MCP 工具对模型完全不可见
出现冲突时控制台会打印 与内置工具冲突、与 <server> 冲突、检测到重复工具名 之类的警告，可据此判断是哪一层挡下的。想让某个工具一定可用，就在服务端改名，或先确认没有插件占用同名工具。
当前版本只发现工具
MCP 的 Prompts（提示词模板）与 Resources（资源）在当前版本不会被发现，控制台里对应的计数恒为 0；实际能用的是 Tools。
常见问题
Q: 配置后不生效？
保存配置后会自动重建 MCP 连接，无需重启；重建结果与启动时一样打印在日志里：
✓ MCP 服务器 'playwright' 已连接 (工具 12 / Prompt 0 / 资源 0 / 模板 0)如果连接失败会有警告日志：
⚠️ MCP 服务器 'playwright' 连接失败: ...Q: 可以配置多少个服务？
没有硬性限制，但每个服务都会消耗资源。建议只配置你实际需要的。
Q: 如何在网上找 MCP 服务？
- GitHub 上搜索
modelcontextprotocol组织下的项目 - npm 上搜索
@modelcontextprotocol包 - Python 社区有
mcp生态的服务器实现
Q: stdio、streamable_http 和 sse 怎么选？
- stdio：本地安装的工具，延迟低，无需网络。适合文件操作、本地计算等
- streamable_http：远程 HTTP 服务，需要网络。适合云 API、别人部署好的服务
- sse：远程 SSE（Server-Sent Events）服务，适合需要服务端推送事件的场景
Q: 从哪里获取 API Token？
取决于你连接的服务。如果是 GitHub MCP，去 GitHub Settings → Developer settings → Personal access tokens 生成；如果是其他第三方服务，去对应服务的管理后台获取。