AstrBot Minecraft 适配器

连接 Minecraft 服务器和 AstrBot，实现消息互通和服务器管理功能。

Note

孪生项目:
AstrBot Adapter(插件版 支持bukkit/paper/folia/velocity)
AstrBotAdapter_Forge

主要功能

• 群服互通，支持将mc服务器与其他连接到AstrBot的平台互通消息
• 服务器管理，支持服务器状态查询，远程指令执行等
• AI聊天，支持游戏内和AstrBot聊天

命令

• mc help - 显示帮助信息和自定义指令列表
• mc status - 查看服务器状态
• mc list - 查看在线玩家列表
• mc player <玩家ID> - 查看玩家详细信息
• mc cmd <指令> - 远程执行服务器指令
• mc bind <游戏ID> - 绑定你的游戏ID
• mc unbind - 解除绑定

当前会话关联多个服务器时，需要区分服务器的指令会显示服务器列表，发送编号选择目标服务器

配置说明

支持添加多服务器，添加的每个服务器将作为独立的平台适配器处理 以下说明仅包含部分重要配置

服务器连接信息

• 服务器ID - 用于区分不同服务器
• 服务器地址、端口、认证token - 用于连接指定mc服务器

消息转发配置

• 聊天消息格式为，消息发送到其他平台时（如QQ），使用的格式，支持占位符{player}和{message}，代表发送者游戏ID和消息内容
• 目标会话 消息转发和消息监听的目标会话，使用会话umo区分，可通过sid指令获取，这个配置标志着MC服务器和群聊的互相绑定关系，群聊中获取mc服务器信息和执行指令等，需要服务器和会话绑定
• 转发前缀 - 带有该前缀的消息将转发到绑定的服务器中
• 转发提醒方式 - 支持 文本提醒/贴表情/不提醒

指令相关配置

• 指令 黑/白名单 -用于保障服务器安全，防止恶意指令影响服务器
• 绑定功能，用户绑定后，提供占位符{sender}用于自定义指令
• 自定义指令
  • 使用<<>>分隔，左侧为自定义指令，右侧为实际在服务器中执行的指令
  • 支持{sender}占位符，会自动替换为发送指令的用户绑定的游戏ID
  • 支持自定义参数占位符，格式为<&xxx&>,左右一致即可自动替换，参数之间使用空格分隔
  • 例 tp <&X&> <&y&> <&z&><<>>tp {sender} <&X&> <&y&> <&z&>
    • 其中<&X&> <&y&> <&z&>为三个自定义参数占位符，在<<>>的左右都要有
    • {sender}会在执行时替换为发送者的游戏ID
    • 假设用户A绑定了游戏ID Misaka，并在群聊中发送tp 114 514 1919,实际执行的指令为tp Misaka 114 514 1919
    • 自定义参数将用户输入的坐标参数传递到了实际指令中，{sender}参数则提供了tp的游戏ID

更新日志

v2.0.2 (2026-2-23)

• 将官方t2i改为本地pillow渲染
• 更新渲染模板
• 优化多服务器查询和渲染逻辑

v2.0.1 (2026-2-15)

• 重构后首个正式版，对应mc端版本 v2.0.5
• 适配ws/http端口共用
• 添加服务器信息图片渲染功能
• 添加转发消息提醒模式选项
• 添加指令黑白名单功能
• 添加自定义指令，支持自定义占位符
• 添加用户绑定功能，用于自定义指令
• 适配多服务器配置
• 优化伪消息平台

v2.0.0-beta (2026-2-2)

• 完全重写，适配全新2.0版本mc服务端插件

v1.3.0 (2025-11-12)

• 添加AI对话功能

v1.2.0 (2025-11-12)

• 进行两次重构
• 修复了数个bug
• 添加快捷转发功能

v1.0.0 (2025-11-09)

• 首次发布
• 支持 WebSocket 实时通信
• 支持 REST API 查询
• 实现基本的消息转发和指令执行功能
• 支持自动重连

许可证

MIT License