AstrBot

Why this agent

AstrBot 是开源的多平台 Agent 助手,集成 QQ、微信、飞书、Telegram。原生支持 MCP(见 astrbot/dashboard/routes/tools.py

astrbot/core/agent/mcp_client.py), 配置文件 <ASTRBOT_ROOT>/data/mcp_server.json,用熟悉的 Claude-Code 形态 {"mcpServers": {<name>: <cfg>}}。canonical UX 是 Web 管理界面 http://localhost:6185 → Tools → MCP → Add,它接受同一份 JSON,自动 CRUD 文件。

Prerequisites

已安装 AstrBot(curl -LsSf https://docs.astrbot.app/install.sh | bash,或者 git clone … && docker compose up -d)。
AstrBot Web UI 可访问(默认 http://localhost:6185)。
espctl 已安装在磁盘上某个稳定位置。
(可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。
必填环境变量,在启动 AstrBot 之前设置 —— ASTRBOT_MCP_STDIO_ALLOWED_COMMANDS 要包含 espctl(完整的 default-allowlist 字符串见 Troubleshooting,必须连同默认 launcher 一起列出,因为环境变量会替换而不是追加默认集合)。

Install snippet (or alternative)

把下面这段粘进 AstrBot 管理面板的 Tools → MCP → Add 表单,或者并入 <ASTRBOT_ROOT>/data/mcp_server.json(管理面板也写这个文件):

{
  "mcpServers": {
    "espctl": {
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

替换:

/path/to/espctl —— 你电脑上 espctl 的完整路径。
CONTROL_BASE_URL —— 你的 Aegis 构建服务器地址。
MCP_AUTH_SECRET —— 构建服务器给你的访问密钥。

或者 —— 拿到预填好的代码片段:

读取 install://astrbot 资源。

管理面板的 “Test” 按钮会重连,不用全量重启;直接改文件则要重启, 除非用面板上的开关再切换一下这个服务条目。

First-run verification

管理面板里,espctl 服务行会变成 Active 状态,工具数显示 ~40 (子进程起来后)。或者直接跟 AstrBot 聊:

你有哪些 espctl 工具?

预期:AstrBot 列出 ~40 个 espctl 工具。

Troubleshooting

**MCP stdio command \espctl` is not allowed.** —— AstrBot 的 stdio 白名单拒了 espctl`。在启动 AstrBot 之前设置环境变量 —— 必须连同默认 launcher 一起列出,因为环境变量是替换不是追加:
```
export ASTRBOT_MCP_STDIO_ALLOWED_COMMANDS=python,python3,py,node,npx,npm,pnpm,yarn,bun,bunx,deno,uv,uvx,espctl
astrbot run
```
服务保存了但 errlogs 报 “command contains unsafe shell metacharacters” —— AstrBot 的白名单也拒绝 command: 字符串里的 shell 元字符。command 用绝对路径,例如 /usr/local/bin/espctl, 不要带 &&、;、| 等。
想用 HTTP 传输不走 stdio? 把 command/args/env 替换成 url: "https://esphome.cloud/mcp/esp-idf" + headers: { "Authorization": "Bearer your-access-key" }。HTTP 路径完全绕开 stdio 白名单。
同一台主机跑多个 AstrBot 实例? 每个实例按 $ASTRBOT_ROOT (默认 = 当前工作目录)分隔;给每个实例配不同的 ASTRBOT_ROOT, 各自的 mcp_server.json 就不会串。

Tested as-of 2026-05-19

AstrBot 特有注意事项

AstrBot 设计上是聊天机器人 —— 它跟 QQ/微信/飞书/Telegram 用户对话。对破坏性固件操作(flash、erase_flash)建议走 human-in-the-loop:AstrBot 用来聊想法,具体构建委托给编程 agent 会话(Claude Code / Cursor / Codex CLI,配 install://*)。
AstrBot 支持每服务 active: false,不删条目就能停用 —— 适合 staging。
管理面板会自动从 ModelScope MCP 服务注册表同步;如果不小心跟 ModelScope 上某个服务重了 espctl 名,下一次同步会覆盖你的本地条目。

Keyboard shortcuts

ESP-IDF MCP 用户手册