The AstrBot MCP server provides comprehensive programmatic control and automation for AstrBot through MCP tools, enabling AI agents to manage, configure, and interact with AstrBot instances.
Core Capabilities:
Control & Monitoring
Restart the AstrBot Core service and wait for availability
Retrieve real-time or historical logs with optional SSE streaming for live monitoring
List all configured message platforms
Messaging Operations
Send rich message chains (text, images, files, videos, voice, replies/quotes) via Web Chat API or directly to platform targets, bypassing the LLM
Retrieve recent conversation history for specific platform sessions (groups/users)
Configuration Management
List, inspect, and search AstrBot configuration files using flexible path notation (dot notation, JSON Pointer, or segment lists)
Apply batch edits (set, add_key, append) with auto-save and hot reload
Drill down into JSON config nodes with optional secret redaction for security
Plugin Ecosystem
Browse the plugin market with search and sorting by update time
Install plugins via URL or local zip path with proxy support for GitHub access
Configure plugins using the same config operation system
MCP Panel Management
Manage MCP server configurations through panel APIs (list, add, update, delete, test)
Key Features: Automatic file upload for local media, proxy handling to avoid request interception, and flexible configuration path handling.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AstrBot MCPshow 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
AstrBot 无法通过 MCP 控制自身。本项目填补了这一空白,为Astrbot开发者提供AI AGENT时代调试插件的自动化工具
⚠️ 本项目提供的是运维级控制能力，使用时请注意：
重启风险 -
restart_astrbot会中断所有正在进行的对话权限管理 - 确保 MCP 客户端的访问权限受控
生产环境 - 建议仅在开发/测试环境使用控制面功能
数据安全 - 日志可能包含敏感信息，注意脱敏处理
本项目与 AstrBot 官方无直接关联，由社区独立维护。
快速开始
安装
# 通过 PyPI 安装（推荐）
pip install astrbotmcp
# 或通过 uv
uv add astrbotmcp{
"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"
}
}
}
}安装完成后，您可以通过以下方式在 MCP 客户端中配置：
注意：npm 安装方式需要您先在系统中安装 Node.js 和 npm。
# 通过 npm 安装
npm install -g astrbotmcp安装完成后，您可以通过以下方式在 MCP 客户端中配置：
{
"mcpServers": {
"astrbot-mcp": {
"command": "npx",
"args": [
"-y",
"@xunxiing/astrbot-mcp@latest"
],
"env": {
"ASTRBOT_BASE_URL": "http://127.0.0.1:6185",
"ASTRBOT_TIMEOUT": "30",
"ASTRBOT_USERNAME": "your_username",
"ASTRBOT_PASSWORD": "your_password"
}
}
}
}环境变量说明
变量 | 说明 | 默认值 |
| AstrBot Dashboard 地址 |
|
| HTTP 请求超时时间 |
|
| Dashboard 用户名 | - |
| Dashboard 密码 | - |
| 日志级别 |
|
| 是否禁用代理（防止本地请求被代理拦截） |
|
| 插件 URL 安装默认代理前缀（ |
|
代理配置说明
如果你在使用代理工具（如 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 Coreget_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 发送消息链（仅 WebUI；无需platform_id/target_id）get_platform_session_messages- 读取会话消息历史
插件市场
browse_plugin_market- 浏览插件市场（搜索/排序）install_astrbot_plugin- Install plugin via URL or local zip path (proxy enabled by default)configure_astrbot_plugin_json- Configure plugin JSON by reusing AstrBot config ops
MCP 面板
manage_mcp_config_panel- Access MCP panel APIs (list/add/update/delete/test)
使用示例
在 Agent 中重启 AstrBot
# Agent 可以直接调用
restart_astrbot()监控 AstrBot 日志
# 实时获取最新日志
logs = get_astrbot_logs(wait_seconds=10)发送消息到指定平台
# 发送带图片的消息链
send_platform_message(
message="Hello from MCP",
images=["/path/to/image.png"]
)# 插件命令请直接发送纯文本，不要命令前缀
send_platform_message(
message="抽老婆帮助"
)技术架构
┌─────────────────┐ 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 文件。
Resources
Looking for Admin?
Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to access the admin panel.