What can you do with this server?

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.

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

{ "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_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`
`ASTRBOTMCP_PLUGIN_PROXY`	插件 URL 安装默认代理前缀（`install_astrbot_plugin`）	`https://gh-proxy.com`

代理配置说明

如果你在使用代理工具（如 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 发送消息链（仅 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 │ └─────────────────┘ └──────────────────┘