Skip to main content
Glama

# AstrBot MCP (Node/TypeScript)

MCP server for operating AstrBot through:

  • AstrBot REST Gateway (astrbot_plugin_mcp_tools) at http://127.0.0.1:6324

This project is a full rewrite in Node + TypeScript.

Install

npm install
npm run build

Related MCP server: AstrBot MCP Server

Run

node dist/src/index.js

or in development:

npm run dev

MCP 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 (false by default)

  • ASTRBOT_LOG_VIEW (compact by default, or raw)

  • ASTRBOT_ENABLE_LOG_NOISE_FILTERING (true by default)

  • ASTRBOT_GITHUB_ACCELERATION (optional GitHub acceleration base URL override for plugin repo install/update; use off to 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 when ASTRBOT_ENABLE_SEARCH_TOOLS=true)

Safety defaults

  • capabilityMode=full by default (as requested)

  • search_tools is disabled by default

  • logs 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 check

  • npm run build - build to dist/

  • 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 unless include_debug=true.

  • trigger_message_reply: session_id can be caller-created for tests. Reuse the same id to continue one synthetic conversation; use a fresh id to start an isolated test session. For GroupMessage, session_id is usually the real group id.

  • trigger_message_reply accepts include_logs=false when you want a low-context response but still keep the send-and-wait behavior.

  • get_message_history: for webchat, use conversation_id or target_id; do not pass the sender id as user_id. conversation_id may 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 by include_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 to wait_for_completion=true. If AstrBot returns a background task_id, MCP will keep polling /tools/tasks/{task_id} until the task is terminal or wait_timeout_seconds is reached.

  • invoke_internal_tool: when a tool only returns a background acceptance message, MCP now puts that text into accepted_reply instead of pretending it is the final reply.

  • invoke_internal_tool: include_logs=true appends simplified task logs to the JSON result; default is false to keep the response short.

  • invoke_internal_tool: include_image_content=true makes MCP return completed image attachments as real MCP image content blocks in addition to compact JSON metadata.

  • invoke_internal_tool: use show_parameters=true to force showing the tool parameter schema, show_parameters=false to hide it, show_arguments=true to echo the actual call arguments, and show_debug=true to include debug payloads.

  • get_internal_tool_task: compact query for one internal tool task by task_id.

  • stream_internal_tool_task: collects compact SSE task events from /tools/tasks/{task_id}/stream and 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 returned config object -> 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: prefer github_acceleration; proxy is 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_plugin when needed.

Available Tools

11 tools
apply_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_path is a local path, this tool will upload it to AstrBot first, then send it as an AstrBot-hosted URL.

    • If file_path/url is 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

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables remote management and debugging of AstrBot servers via SSH, including log monitoring, status checks, and command execution.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to manage AzurLaneAutoScript (ALAS) automation: start/stop processes, read/write configs, monitor runtime status, and schedule tasks via MCP tools.
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      23
      72 npm
      MIT