Skip to main content
Glama
actforever

GTNH MCP

by actforever
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

GTNH MCP

让 AstrBot 群聊通过经过身份校验的 MCP 工具执行 GTNH 日常运维，并由管理员确认后恢复备份。

支持在线玩家、公告、保存世界、白名单管理、备份查询、恢复申请与进度查询。恢复支持 backups/*.zip 和 *.tar.gz，处理 WORLD_DIRECTORY（默认 World）和 visualprospecting，保留旧存档并支持失败回滚。

回档后反悔也可以撤销： 管理员查询成功任务编号，让机器人“撤销这次回档”，再发送新的 /gtnh_confirm <撤销任务编号>。程序恢复那次回档前的完整存档，并保留撤销前的当前世界；不会合并两段游戏进度。撤销本身也是恢复任务，成功后仍可再次撤销，详见 撤销流程。

使用 FastMCP Streamable HTTP，默认地址 http://127.0.0.1:8000/mcp。MCP 和 AstrBot 使用 Linux Docker host 网络；恢复服务独立持有 Docker 控制权限，通过私有 Unix socket 接受请求。

运行架构

flowchart TD
    QQ[QQ 群友] <-->|QQ 官方机器人 API| AstrBot[现有 AstrBot：内置 QQ 接入 + GTNH 插件]
    AstrBot <-->|固定 Bearer 密钥 / Streamable HTTP| MCP[MCP 服务：密钥校验与工具]
    MCP <-->|RCON：查询、公告、保存、白名单| GTNH[GTNH 容器]
    MCP <-->|私有 Unix socket| Restore[恢复服务：备份校验与回档]
    Restore -->|Docker API：停启与重启策略| Docker[Docker Engine]
    Docker --> GTNH
    Restore <-->|RCON stop / list| GTNH
    Restore --> Backups[backups：现有 ZIP / tar.gz]
    Restore --> World[World + visualprospecting：读写]
    Restore --> State[任务日志 + 暂存目录 + previous 旧存档]

插件从真实群消息读取身份，在插件内检查允许群和管理员配置；身份不由模型填写。插件只通过原申请人在原群发送的 /gtnh_confirm <任务编号> 执行确认，不向模型注册确认工具。MCP 和恢复服务只校验固定访问密钥，持有密钥的直接客户端可调用全部工具。不要在 AstrBot 原生 MCP 页面重复添加服务，否则会绕过插件的群权限和人工确认入口。

MCP Inspector 选择 Streamable HTTP，地址 http://127.0.0.1:8000/mcp，添加请求头 Authorization: Bearer <AUTH_SECRET>（将占位符替换为 .env 的实际值）。默认仅 NAS 本机可访问；本地电脑先执行 ssh -N -L 8000:127.0.0.1:8000 pineclone.nas。/health 无需密钥，健康不代表 MCP 已授权。具体步骤见 部署教程。

容器内游戏根目录默认 /gtnh，备份为 /gtnh/backups；项目镜像工作目录仍为 /app。两个服务通过 .env 配置，恢复服务额外加入 Docker socket 的实际 GID，健康检查间隔和启动宽限期均为 10 秒。

聊天侧复用已有 AstrBot 的内置 QQ 官方机器人接入，GTNH 插件安装在该实例内。compose.chat.yaml 仅供尚未部署 AstrBot 的用户选择使用，不需要另外启动一个 AstrBot。群和管理员权限按 /gtnh_identity 返回的平台与身份填写，不能直接套用普通 QQ 群号、QQ 号。

双服务使用同一项目镜像、不同入口。MCP 以非 root 用户运行，不挂载游戏目录或 Docker socket；恢复服务处理文件与容器操作，不开放 TCP 端口。两者共享操作锁和维护标记，回档期间暂停普通 RCON 工具。任务日志持久化在状态卷中，旧世界保存在服务端 .gtnh-restore/<任务编号>/previous/。运行时不依赖 SSH。

NAS 已只读确认 /volume2/sharev9/minecraft/gtnh 下为 World、visualprospecting 和 backups；抽查的日期命名 ZIP 索引包含这两个顶层目录，使用 Deflate。程序不依赖日期命名规则，也不会把 World 改成 Worlds。索引检查不等于完整备份校验或实际恢复验收；server.properties 因 SSH 读取权限不足未核实，RCON 仍需部署时确认。

回档前必须调整 GTNH 启动方式： 原 startserver-java9.sh 的 while true 会在 RCON stop 后再次启动 Java。使用 单次启动脚本，由 Docker restart: unless-stopped 接管自动重启，具体修改和完整部署顺序见下方教程。

Related MCP server: AstrBot MCP

部署与开发

本地开发（Windows PowerShell）：

uv sync --locked --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .

首次部署请先在隔离 GTNH 测试服使用真实备份验收。save_world 只执行保存，不创建备份；本项目读取已有备份，不接管备份生成计划。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • AstrBot MCP

    xunxiing
    A
    license
    A
    quality
    C
    maintenance
    Provides operational control and automation tools for AstrBot developers, enabling plugin debugging, configuration management, message sending, log monitoring, and bot restart capabilities through AI agents.
    11
    7 npm
    9
    MIT

  • Minecraft Server MCP

    tamo2918
    A
    license
    B
    quality
    D
    maintenance
    Provides comprehensive administrator-level control for Minecraft Java Edition servers, allowing AI to manage world generation, server configuration, and player moderation. It enables remote execution of RCON commands, NBT data parsing, and automated backup management through the Model Context Protocol.
    40
    MIT

  • AstrBot MCP Server

    LilycleHeart
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables remote management and debugging of AstrBot servers via SSH, including log monitoring, status checks, and command execution.
    -