AstrBot

Why this agent

AstrBot is an open-source all-in-one agent assistant that integrates with mainstream messaging platforms (QQ, WeChat, Feishu, Telegram). It speaks MCP — per astrbot/dashboard/routes/tools.py

• astrbot/core/agent/mcp_client.py — with config persisted at <ASTRBOT_ROOT>/data/mcp_server.json in the familiar Claude-Code-shape {"mcpServers": {<name>: <cfg>}}. The canonical UX is the Web dashboard at http://localhost:6185 → Tools → MCP → Add which accepts the same JSON envelope and CRUDs it for you.

Prerequisites

• AstrBot installed (curl -LsSf https://docs.astrbot.app/install.sh | bash, or git clone … && docker compose up -d).
• AstrBot Web UI reachable at http://localhost:6185 (or the host you configured).
• espctl installed at a stable path on disk.
• (Optional, for remote builds) the Aegis build server URL + MCP_AUTH_SECRET.
• Required env var, set BEFORE starting AstrBot — ASTRBOT_MCP_STDIO_ALLOWED_COMMANDS must include espctl (see Troubleshooting for the full default-allowlist string to keep).

Install snippet (or alternative)

Paste this into the AstrBot dashboard’s Tools → MCP → Add form, or merge it into <ASTRBOT_ROOT>/data/mcp_server.json (the dashboard writes there too):

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

Replace:

• /path/to/espctl — full path to your espctl executable.
• CONTROL_BASE_URL — your Aegis build server URL.
• MCP_AUTH_SECRET — the access key your build server gave you.

Or grab the same snippet pre-filled:

Read the install://astrbot resource.

The dashboard’s “Test” button reconnects without a full restart; direct file edits require restart unless you toggle the server entry via the dashboard.

First-run verification

In the dashboard, the MCP server row for espctl flips to Active with a tool count of ~40 once the subprocess starts. Or chat with AstrBot:

What espctl tools do you have?

Expected: AstrBot lists ~40 espctl tools.

Troubleshooting

• **MCP stdio command \espctl` is not allowed.** — AstrBot's stdio allowlist rejected espctl`. Set the env var BEFORE starting AstrBot — and include the default launchers because the env var REPLACES (not augments) the default set:

  export ASTRBOT_MCP_STDIO_ALLOWED_COMMANDS=python,python3,py,node,npx,npm,pnpm,yarn,bun,bunx,deno,uv,uvx,espctl
  astrbot run
  

• Server saved but errlogs show “command contains unsafe shell metacharacters” — AstrBot’s allowlist also rejects shell-meta characters in the command: string. Use an absolute path like /usr/local/bin/espctl with no &&, ;, |, etc.
• Want HTTP transport instead of stdio? Replace command/args/env with url: "https://esphome.cloud/mcp/esp-idf" and headers: { "Authorization": "Bearer your-access-key" }. HTTP bypasses the stdio allowlist entirely.
• Multiple AstrBot instances on the same host? Each instance keys off $ASTRBOT_ROOT (default = cwd); set distinct roots for distinct mcp_server.json files.

Tested as-of 2026-05-19

AstrBot-specific notes

• AstrBot is a chat-bot by design — it talks to QQ/WeChat/Feishu/ Telegram users. For destructive firmware operations (flash, erase_flash), consider a human-in-the-loop pattern: use AstrBot for chat/ideation, delegate concrete builds to a coding-agent session (Claude Code / Cursor / Codex CLI) with install://* configured.
• AstrBot also supports per-server active: false to disable a server without removing the entry — useful for staging.
• The dashboard auto-syncs from ModelScope’s MCP server registry; if you accidentally end up with a duplicate espctl name, the ModelScope sync will overwrite yours on next sync.