AstrBot MCP
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 "Deploy 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 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 (Node/TypeScript)
MCP server for operating AstrBot through:
AstrBot REST Gateway (
astrbot_plugin_mcp_tools) athttp://127.0.0.1:6324
This project is a full rewrite in Node + TypeScript.
Install
npm install
npm run buildRelated MCP server: AstrBot MCP Server
Run
node dist/src/index.jsor in development:
npm run devMCP config example
{
"mcpServers": {
"astrbot-mcp": {
"command": "node",
"args": ["D:/绋嬪簭/astrbotmcp/dist/src/index.js"],
"env": {
"ASTRBOT_GATEWAY_URL": "http://127.0.0.1:6324",
"ASTRBOT_GATEWAY_TOKEN": "iaushdqwuikdwq78ui"
}
}
}
}Environment variables
Required:
ASTRBOT_GATEWAY_TOKEN
Optional:
ASTRBOT_GATEWAY_URL(default:http://127.0.0.1:6324)ASTRBOT_GATEWAY_TIMEOUT(default:30000, milliseconds)ASTRBOT_CAPABILITY_MODE(search|readonly|minimize|full, default:full)ASTRBOT_ENABLE_SEARCH_TOOLS(falseby default)ASTRBOT_LOG_VIEW(compactby default, orraw)ASTRBOT_ENABLE_LOG_NOISE_FILTERING(trueby default)ASTRBOT_GITHUB_ACCELERATION(optional GitHub acceleration base URL override for plugin repo install/update; useoffto disable MCP auto acceleration)
Tool groups
system: status, compact logs, logs by id, restart
platforms: list, stats, details
providers: list, current, details
configs: inspect core/plugin, search, patch core/plugin
plugins: list/details/config read+replace/install/set-enabled/reload/update/uninstall
messages: trigger replies, recent sessions, history
astrbot_tools: list/details/invoke/task/stream
mcp_servers: list/register/update/uninstall/test
personas: list/details/upsert/delete
skills: list/install/toggle/delete
subagents: list/config inspect/config update
cron: list/upsert/delete
discovery:
search_tools(only whenASTRBOT_ENABLE_SEARCH_TOOLS=true)
Safety defaults
capabilityMode=fullby default (as requested)search_toolsis disabled by defaultlogs return compact/noise-filtered output by default
restart and logs use the gateway only; no separate dashboard auth is required
Scripts
npm run check- type checknpm run build- build todist/npm run dev- run directly from TypeScript
Message semantics
trigger_message_reply: injects an inbound message through/events/injections/message, optionally overrides the target LLM provider/model/streaming flags, waits for the event to settle, and by default returns only the bot reply text. Internal metadata is hidden unlessinclude_debug=true.trigger_message_reply:session_idcan be caller-created for tests. Reuse the same id to continue one synthetic conversation; use a fresh id to start an isolated test session. ForGroupMessage,session_idis usually the real group id.trigger_message_replyacceptsinclude_logs=falsewhen you want a low-context response but still keep the send-and-wait behavior.get_message_history: forwebchat, useconversation_idortarget_id; do not pass the sender id asuser_id.conversation_idmay also be a synthetic id you created earlier during injection tests.
Internal tool semantics
list_astrbot_tools: compact list of AstrBot internal tools. This is the clearest discovery entry for LLMs.list_internal_tools: same compact list, kept for backward compatibility.get_internal_tool_details: compact tool metadata by default, with full parameter schema controlled byinclude_parameters.invoke_internal_tool: compact invoke result by default. It returns the tool parameter schema only on the first call for the same tool within the current MCP process, then hides it on later calls to reduce context use.invoke_internal_tool: now defaults towait_for_completion=true. If AstrBot returns a backgroundtask_id, MCP will keep polling/tools/tasks/{task_id}until the task is terminal orwait_timeout_secondsis reached.invoke_internal_tool: when a tool only returns a background acceptance message, MCP now puts that text intoaccepted_replyinstead of pretending it is the finalreply.invoke_internal_tool:include_logs=trueappends simplified task logs to the JSON result; default isfalseto keep the response short.invoke_internal_tool:include_image_content=truemakes MCP return completed image attachments as real MCPimagecontent blocks in addition to compact JSON metadata.invoke_internal_tool: useshow_parameters=trueto force showing the tool parameter schema,show_parameters=falseto hide it,show_arguments=trueto echo the actual call arguments, andshow_debug=trueto include debug payloads.get_internal_tool_task: compact query for one internal tool task bytask_id.stream_internal_tool_task: collects compact SSE task events from/tools/tasks/{task_id}/streamand returns the latest task snapshot plus streamed events.
Plugin workflow
list_plugins: compact plugin list for discovery only. It no longer returns full handlers/config noise.get_plugin_details: compact metadata plus command list for one plugin. Config is intentionally separated.get_plugin_config_file: fetch the full editable plugin config object. This is the main read step before changing a plugin config.replace_plugin_config_file: replace the full plugin config object and auto-reload the plugin.Normal plugin config workflow:
get_plugin_details->get_plugin_config_file-> edit the returnedconfigobject ->replace_plugin_config_file.patch_plugin_config: only for small path-level edits. Prefer the full read-edit-save flow above for normal configuration work.install_plugin/update_plugin: for GitHub repos, MCP now auto-detects a reachable GitHub acceleration prefix and uses it by default.install_plugin/update_plugin: prefergithub_acceleration;proxyis kept only as a deprecated alias for backward compatibility.Recommended flow:
install_plugin->get_plugin_details->get_plugin_config_file->replace_plugin_config_file->uninstall_pluginwhen needed.
Available Tools
11 toolsapply_astrbot_config_opsA
Apply multiple edits to an AstrBot config, then save + hot reload.
Supported ops (batch in a single tool call):
{"op":"set","path":,"value":}
{"op":"add_key","path":<parent_path>,"key":,"value":}
{"op":"append","path":<list_path>,"value":}
path accepts dot path, JSON Pointer, or segment list.
Inputs: conf_id (required), ops (required), create_missing (required). Returns: object
browse_plugin_marketA
查看 AstrBot 插件市场(支持搜索与按时间排序)。
用法:
mode="latest": 按
updated_at倒序,返回第 start ~ start+count-1 条(start 从 1 开始)mode="search": 按 query 搜索(名称/简介/标签/作者/仓库),再按
updated_at倒序
返回字段:
total_plugins: 插件市场总数(未过滤)
matched_plugins: 搜索命中数(mode=search)
plugins: 列表(包含 name/desc/tags/stars/updated_at)
Inputs: mode, query, start, count, +2 more. Returns: object
get_astrbot_logsA
获取 AstrBot 日志。
如果 wait_seconds <= 0:立即返回 /api/log-history 的数据。
如果 wait_seconds > 0:通过 /api/live-log SSE 持续读取指定秒数内的新日志。
Inputs: wait_seconds, max_events. Returns: object
get_message_platformsB
获取 AstrBot 中配置的消息平台列表,对应 /api/config/platform/list。
Inputs: no named parameters. Returns: object
get_platform_session_messagesA
Get a platform target's recent messages from AstrBot logs.
This tool intentionally uses AstrBot's log broker history (/api/log-history) as the source of truth, since some AstrBot builds do not persist platform conversation history under /api/conversation/detail for group/user targets.
Args:
target_id: Platform target ID (e.g. group_id like "1030223077").
platform_id: Optional platform id (e.g. "napcat"). If omitted, use the first enabled platform.
message_type: "GroupMessage" or "FriendMessage" (default: "GroupMessage").
wait_seconds: If > 0, poll and return SSE-like events for up to this many seconds.
max_messages: Max number of history items to return (from the tail).
poll_interval_seconds: Poll interval when wait_seconds > 0.
Inputs: target_id (required), platform_id, message_type, wait_seconds, +2 more. Returns: object
inspect_astrbot_configB
Inspect a node in an AstrBot config JSON.
This tool is designed for step-by-step exploration:
Start with path=None to list top-level keys.
Then drill down by providing a deeper path.
Inputs: conf_id (required), system_config (required), path (required), include_value (required), +3 more. Returns: object
list_astrbot_config_filesB
List AstrBot config files (abconfs), via /api/config/abconfs.
Inputs: no named parameters. Returns: object
restart_astrbotB
重启 AstrBot Core,对应 /api/stat/restart-core。 重启后会等待 AstrBot 重新启动并可用。
Inputs: no named parameters. Returns: object
search_astrbot_config_pathsB
Search AstrBot config and return only matched key paths (no big values).
Modes:
key only: provide key_query
key + value: provide key_query and value_query (matches leaf values of primitive types)
Returns:
results: [{path, path_pointer, path_dot, type}, ...]
Inputs: conf_id (required), system_config (required), key_query (required), value_query (required), +2 more. Returns: object
send_platform_messageA
通过 AstrBot 的 Web Chat API 发送消息链(支持文本、图片、文件等)。
参数:
platform_id: 平台 ID,例如 "webchat" 或配置中的平台 ID。
message_chain: 消息链,由 MessagePart 列表组成。
文本: {"type": "plain", "text": "..."}
回复: {"type": "reply", "message_id": "..."}
图片/文件/语音/视频: {"type": "image"|"file"|"record"|"video", "file_path": "本地路径或URL"} 或 {"type": "...", "url": "http(s) URL"}
message / images / files / videos / records: 可选便捷参数;当未传 message_chain 时,会自动拼成消息链。
session_id: 可选的平台会话 ID;如果为空,会自动为该平台创建新会话。
selected_provider / selected_model: 可选,指定 AstrBot 内部的 provider/model。
enable_streaming: 是否启用流式回复(影响 AstrBot 返回的 SSE 事件类型)。
Inputs: platform_id (required), message_chain, message, images, +15 more. Returns: object
send_platform_message_directB
Directly send a message chain to a platform group/user (bypass LLM).
This calls AstrBot dashboard endpoint: POST /api/platform/send_message
Notes:
This is for sending to a real platform target (group/user), not WebChat.
Media parts:
If
file_pathis a local path, this tool will upload it to AstrBot first, then send it as an AstrBot-hosted URL.If
file_path/urlis an http(s) URL, it will be forwarded as-is.
Inputs: platform_id (required), target_id (required), message_chain, message, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have distinct purposes, such as config management, message handling, and logging. However, send_platform_message and send_platform_message_direct could be confusing as both involve sending messages, though one targets WebChat and the other real platforms. The descriptions help clarify this, but some overlap exists.
Tool names generally follow a consistent snake_case pattern with descriptive verbs and nouns, like apply_astrbot_config_ops and get_astrbot_logs. There are minor deviations, such as browse_plugin_market using 'browse' instead of 'list' or 'get', but overall the naming is predictable and readable.
With 11 tools, the count is well-suited for managing an AstrBot instance, covering config operations, messaging, logging, and system control. Each tool serves a clear function without redundancy, making the set comprehensive yet manageable for the domain.
The toolset provides strong coverage for AstrBot management, including config inspection, editing, messaging, logging, and system restarts. A minor gap is the lack of tools for plugin installation or management beyond browsing the market, but core workflows are well-supported.
Maintenance
Related MCP Connectors
Run your Krtuworks apps from an AI agent: setup, remote config, stats, players, bug reports.
Deploy apps from GitHub, read build/runtime logs, and manage your app's users from your AI agent.
The AI admin for Discord: manage channels, roles, members, moderation and automations.
Autonomous and governed SRE & MLOps control plane for AI agent platforms.
Related MCP Servers
- AlicenseAqualityDmaintenanceConnects AI agents to Minecraft servers via RCON to execute commands, monitor logs, and perform read-only SQLite database queries. It is specifically designed to facilitate AI-assisted plugin development, live debugging, and automated testing workflows.612MIT
- FlicenseNot gradedqualityDmaintenanceEnables remote management and debugging of AstrBot servers via SSH, including log monitoring, status checks, and command execution.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage AzurLaneAutoScript (ALAS) automation: start/stop processes, read/write configs, monitor runtime status, and schedule tasks via MCP tools.1MIT
- AlicenseBqualityDmaintenanceEnables AI tools to perform server operations such as log inspection, system monitoring, code management, Nginx and certificate management, with support for local and remote SSH modes and built-in security controls.2372 npmMIT