AstrBot

You can manage AstrBot Core through an MCP (Minecraft Control Protocol) server, enabling automated control and debugging of AstrBot plugins and workflows. This MCP server lets you restart AstrBot, fetch logs, configure plugins, and perform other operational tasks from your MCP client, streamlining development and testing workflows.

How to use

Use an MCP client to connect to AstrBot MCP services. You can restart the core to apply changes or recover from issues, pull live or historical logs for debugging, and send messages or run configuration commands across configured platforms. You can also inspect and adjust AstrBot configuration files on the fly, apply multiple config operations at once, and search for specific configuration paths to quickly locate settings.

How to install

Prerequisites: you need Python and pip, or Node.js with npm, depending on how you want to install the MCP bridge for AstrBot.

Option A: Install with Python via pip (recommended) and run the MCP bridge from there.

pip install astrbotmcp

uv add astrbotmcp

After installation, configure the MCP client to connect to AstrBot MCP using the provided startup options.

Option B: Install with Node.js and npm for the MCP bridge.

npm install -g astrbotmcp

Configure the MCP client with either of the following example configurations to run AstrBot MCP as a local process.

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

Notes on environment and proxy

Environment variables control how AstrBot MCP connects to the dashboard and how verbose the logs are. The base URL defaults to the local dashboard, and you can adjust timeouts and credentials to fit your environment.

If you are using a proxy with local development tools, you can disable the proxy for local requests to prevent interception issues.

Security and usage notes

Limit access to the MCP client to trusted operators. The control surface includes actions such as restarting AstrBot Core and reading logs, which can disrupt ongoing conversations and sensitive data streams.

In production, restrict permissions and consider enabling logging redaction so sensitive data does not appear in logs.

Operational examples

Restart AstrBot from your MCP client to apply code or plugin updates without manually interacting with the host.

Fetch logs to monitor for errors or to study bot behavior during development and testing.

Architecture overview

The MCP client communicates with the astrbot-mcp server over the MCP protocol, which forwards requests to the AstrBot Core and its dashboard. This enables automated control and debugging workflows from your preferred MCP client.

Available tools

restart_astrbot

Restart AstrBot Core to apply updates or recover from issues.

get_astrbot_logs

Retrieve real-time or historical logs from AstrBot Core.

get_message_platforms

List all message platforms configured for AstrBot.

list_astrbot_config_files

List all AstrBot configuration files under /api/config/abconfs.

inspect_astrbot_config

Inspect JSON configuration nodes to understand structure.

apply_astrbot_config_ops

Batch set/add operations to the AstrBot config with automatic save and hot reload.

search_astrbot_config_paths

Search configuration paths by key (and optional value).

send_platform_message

Send a message chain to a target platform via Web Chat API.

send_platform_message_direct

Send a message directly to a platform, bypassing the LLM.

get_platform_session_messages

Read historical messages from a platform session.

browse_plugin_market

Browse and search the plugin market for AstrBot extensions.