How do I use AstrBot MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AstrBot MCP show me the latest AstrBot logs from the last 5 minutes" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

AstrBot MCP by xunxiing

AstrBot MCP

MCP Badge

AstrBot 无法通过 MCP 控制自身。本项目填补了这一空白,为Astrbot开发者提供AI AGENT时代调试插件的自动化工具

⚠️ 本项目提供的是运维级控制能力，使用时请注意：

重启风险 - restart_astrbot 会中断所有正在进行的对话
权限管理 - 确保 MCP 客户端的访问权限受控
生产环境 - 建议仅在开发/测试环境使用控制面功能
数据安全 - 日志可能包含敏感信息，注意脱敏处理

本项目与 AstrBot 官方无直接关联，由社区独立维护。

快速开始

安装

# 通过 PyPI 安装（推荐） pip install astrbotmcp # 或通过 uv uv add astrbotmcp

安装完成后，您可以通过以下方式在 MCP 客户端中配置：

{ "mcpServers": { "astrbot-mcp": { "command": "uvx", "args": [ "--from", "astrbotmcp", "astrbot-mcp" ], "env": { "ASTRBOT_BASE_URL": "http://127.0.0.1:6185", "ASTRBOT_TIMEOUT": "30", "ASTRBOT_USERNAME": "your_username", "ASTRBOT_PASSWORD": "your_password" } } } }

注意：npm 安装方式需要您先在系统中安装 Node.js 和 npm。

# 通过 npm 安装 npm install -g astrbotmcp

安装完成后，您可以通过以下方式在 MCP 客户端中配置：

{ "mcpServers": { "astrbot-mcp": { "command": "npx", "args": [ "astrbotmcp" ], "env": { "ASTRBOT_BASE_URL": "http://127.0.0.1:6185", "ASTRBOT_TIMEOUT": "30", "ASTRBOT_USERNAME": "your_username", "ASTRBOT_PASSWORD": "your_password" } } } }

环境变量说明

变量	说明	默认值
`ASTRBOT_BASE_URL`	AstrBot Dashboard 地址	`http://127.0.0.1:6185`
`ASTRBOT_TIMEOUT`	HTTP 请求超时时间	`30`
`ASTRBOT_USERNAME`	Dashboard 用户名	-
`ASTRBOT_PASSWORD`	Dashboard 密码	-
`ASTRBOT_LOG_LEVEL`	日志级别	`INFO`
`ASTRBOTMCP_DISABLE_PROXY`	是否禁用代理（防止本地请求被代理拦截）	`true`

代理配置说明

如果你在使用代理工具（如 Clash、V2Ray 等），可能会遇到 502 Bad Gateway 错误，这是因为本地请求被代理拦截导致的。

解决方案：

默认行为：AstrBot MCP 默认禁用代理（ASTRBOTMCP_DISABLE_PROXY=true），确保本地请求直接发送到 AstrBot。
如果需要使用代理：设置 ASTRBOTMCP_DISABLE_PROXY=false，但请注意这可能导致本地 API 请求失败。
推荐配置：对于本地 AstrBot 实例，始终禁用代理：

{ "mcpServers": { "astrbot-mcp": { "command": "uvx", "args": [ "--from", "astrbotmcp", "astrbot-mcp" ], "env": { "ASTRBOT_BASE_URL": "http://127.0.0.1:6185", "ASTRBOTMCP_DISABLE_PROXY": "true" } } } }

可用 MCP Tools

控制面工具

restart_astrbot - 重启 AstrBot Core
get_astrbot_logs - 获取实时/历史日志
get_message_platforms - 列出已配置的消息平台

配置工具

list_astrbot_config_files - 列出所有 AstrBot 配置文件（/api/config/abconfs）
inspect_astrbot_config - 分层查看 JSON 配置节点（key / array length / value）
apply_astrbot_config_ops - 批量 set / add_key / append，并自动保存 + 热重载（/api/config/astrbot/update）
search_astrbot_config_paths - 按 key（可选再按 value）搜索配置，返回匹配项的路径（不返回大段内容）

消息工具

send_platform_message - 通过 Web Chat API 发送消息链
send_platform_message_direct - 直接发送到平台（绕过 LLM）
get_platform_session_messages - 读取会话消息历史

插件市场

browse_plugin_market - 浏览插件市场（搜索/排序）

使用示例

在 Agent 中重启 AstrBot

# Agent 可以直接调用 restart_astrbot()

监控 AstrBot 日志

# 实时获取最新日志 logs = get_astrbot_logs(wait_seconds=10)

发送消息到指定平台

# 发送带图片的消息链 send_platform_message( platform_id="webchat", message="Hello from MCP", images=["/path/to/image.png"] )

技术架构

┌─────────────────┐ HTTP API ┌──────────────────┐ │ MCP Client │───────────────────>│ astrbot-mcp │ │ (Cursor/Cline) │ (MCP Protocol) │ (FastMCP Server)│ └─────────────────┘ └────────┬─────────┘ │ │ HTTP ↓ ┌─────────────────┐ ┌──────────────────┐ │ AstrBot Core │<───────────────────│ AstrBot │ │ + Plugins │ (Dashboard API) │ Dashboard │ └─────────────────┘ └──────────────────┘

开发与贡献

# 克隆项目 git clone https://github.com/yourusername/astrbot-mcp.git cd astrbot-mcp # 安装依赖 uv sync # 本地运行 uv run --project . astrbot-mcp

许可证

MIT License - 详见 LICENSE 文件。

AstrBot MCP

AstrBot MCP

本项目与 AstrBot 官方无直接关联，由社区独立维护。

快速开始

安装

环境变量说明

代理配置说明

可用 MCP Tools

控制面工具

配置工具

消息工具

插件市场

使用示例

在 Agent 中重启 AstrBot

监控 AstrBot 日志

发送消息到指定平台

技术架构

开发与贡献

许可证

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API