HeadlessMc

HeadlessMc - MCP

适用于 HeadlessMc 的 MCP 服务：让 AI Agent 安装、启动和控制 Minecraft: Java Edition。

HMC | HMC-Specifics | HMC-Skill

警告

这是一个原型。欢迎提供反馈和功能需求。

借助此 MCP 服务，Claude Code、Codex、Cursor 和其他 MCP 客户端可以：

• 安装 vanilla、Fabric、Forge 和 NeoForge 版本、Java，以及来自 Modrinth 的模组（HeadlessMc 能做的一切），
• 同时启动多个客户端和服务端，可选择以无头模式运行（无显示器或 GPU，例如在 CI 或 Docker 中）， 每个客户端都使用独立的配置档案（包含自身模组、配置和世界存档的游戏目录），
• 控制正在运行的客户端：读取屏幕、点击按钮、输入文字、聊天、运行命令、 连接到服务端等。
• 读取每个实例的日志，并向服务端发送控制台命令。

设置

Agent	安装
Claude Code	/plugin install headlessmc-mcp --marketplace headlesshq/headlessmc-mcp
OpenAI Codex	codex plugin marketplace add headlesshq/headlessmc-mcp，然后打开 /plugins，切换到 HeadlessMc MCP 选项卡，再选择 Install plugin
GitHub Copilot CLI	copilot plugin marketplace add headlesshq/headlessmc-mcp，然后运行 copilot plugin install headlessmc-mcp@headlessmc-mcp
Cursor	克隆此仓库并将 plugin 复制到 ~/.cursor/plugins/local/headlessmc-mcp，然后选择 Developer: Reload Window
Gemini CLI	gemini extensions install https://github.com/headlesshq/headlessmc-mcp

如需了解 HeadlessMc 本身的使用说明（安装它、在 CI 中使用 MC-Runtime-Test 测试模组），也请安装 headlessmc-skill。

工具

工具	描述
hmc	运行任意 HeadlessMc 命令行命令，例如 version install fabric 1.21.5、mod search sodium、login。长时间运行的命令会持续执行，可使用 hmc_job 轮询。
hmc_job	查看正在运行的 hmc 命令的输出和状态。
launch_client	安装并启动客户端（版本、加载器或配置、无头模式、离线模式、要加入的服务、JVM 参数），并等待其显示主菜单。
start_server	创建并启动 Paper/Fabric/Purpur/Forge/NeoForge/vanilla 服务，并等待其加载世界。
list_profiles、create_profile、delete_profile	管理配置：各自拥有独立游戏目录的客户端设置。
list_instances	查看所有已启动客户端和服务及其状态。
instance_log	查看实例输出的最新内容，可选择使用正则表达式筛选。
server_command	向服务发送控制台命令并返回其输出。
stop_instance	退出客户端或停止服务（也可强制结束）。
get_screen	以 JSON 格式返回当前屏幕：包含按钮和文本字段的 ID、文本及位置。
get_state	JSON：是否在世界中、是否已死亡、屏幕，以及位置、生命值、维度、服务、延迟、TPS、玩家数等指标。
click、set_text、press_key	与当前屏幕交互。click 会返回其跳转到的屏幕。
chat	发送聊天消息或 /command。
connect、disconnect	加入或离开服务。
wait_for	等待 in_world、menu、screen:<Name>、log:<regex> 或 exit。
game_command	在游戏内运行任意 HMC-Specifics 命令（help、metrics、render、respawn，以及其他模组的命令）。

资源模板：hmc://instances/{id}/log。

同时运行多个客户端

每个运行中的客户端都需要使用独立的游戏目录，否则它们会互相覆盖文件并共用模组文件夹。 launch_client 可选接受 profile：一个拥有独立游戏目录的 HeadlessMc 配置；如果该目录不存在，则会在 <HeadlessMc data dir>/client/<profile> 中创建。若未指定配置，客户端会使用其版本的默认游戏目录；如果同一版本的另一个客户端已在该目录中运行，MCP 服务会自动创建新的配置（fabric-1.21.8-2 等）。所有配置共用版本、库和资源。 Agent 可以为不同设置保留配置，并使用 mod add mod <slug> <profile> 向其中添加模组。

游戏控制

游戏控制适用于 HMC-Specifics 支持的所有 Minecraft 版本和 Mod 加载器（1.7.10 至 26.x，Forge、Fabric、NeoForge）。 服务会下载匹配的 HMC-Specifics jar，并在启动客户端前，将它与版本无关的 hmc-mcp-bridge mod 一起放入客户端的 mods 文件夹。

• 根项目（src/）是一个 Quarkus 应用，即 MCP 服务。它直接使用 HeadlessMc 的 CDI bean 和 picocli 命令，类似于 headlessmc-web。stdout 是 MCP 通道，因此 HeadlessMc 的控制台输出和进度条会被捕获，并作为工具结果返回。
• hmc-mcp-bridge 是一个不绑定 Minecraft 版本的 mod。它使用 HMC-Specifics API，并在 HMC-Specifics 初始化后于环回接口上启动一个小型 HTTP 服务。MCP 服务会通过 -Dhmc.mcp.token 和 -Dhmc.mcp.portFile 传入一个随机令牌和端口文件。没有令牌时，该 mod 不会执行任何操作。 命令输出与游戏日志分开返回，JSON 命令会以机器可读的形式返回屏幕和状态。

Agent 也可以控制你使用任意启动器自行启动的客户端（Minecraft Launcher、Prism、MultiMC、IDE 的运行配置等）。将两个 mod 放入 mods 文件夹：

• 适用于你的 Minecraft 版本和 Mod 加载器的 HMC-Specifics，
• 来自发布版本的 hmc-mcp-bridge，所有版本和 Mod 加载器通用一个 jar。

如果装有这些 mod 的游戏不是由 MCP 服务启动的，bridge 会创建一个随机令牌，在 127.0.0.1 的空闲端口上监听，并将游戏注册到用户状态目录中的 headlessmc-mcp/instances/<pid>.json（Linux 上为 $XDG_STATE_HOME，否则为 ~/.local/state；macOS 上为 ~/Library/Application Support；Windows 上为 %LOCALAPPDATA%\state）。 该文件仅你可读，并会在游戏退出时删除。list_instances 会读取这些注册信息，因此游戏会显示为已附加实例，游戏工具也能像控制已启动的客户端一样使用。日志来自 logs/latest.log。 MCP 服务不会自行停止已附加的游戏，且这些游戏没有可供 server_command 使用的控制台。 使用 -Dhmc.mcp.enabled=false 启动游戏即可关闭 bridge。

询问用户

有些操作需要由用户而非 Agent 执行。MCP 客户端支持时，MCP 服务会使用 elicitation：

• Minecraft EULA：首次启动服务器前，start_server 会通过复选框请求用户接受 EULA。 如果不支持 elicitation，Agent 必须询问用户并传入 acceptEula。
• Microsoft 登录：login 命令会请求客户端打开 Microsoft 设备代码页面（URL 模式），用户可在浏览器中登录，Agent 不会接触凭据。
• HeadlessMc 命令的提示词会以表单形式展示给用户。不会请求密码和令牌，因为 MCP 规范禁止在表单 elicitation 中请求这些内容。
• 删除含文件的配置会请求确认。

较长的安装和启动操作会发送进度通知，在客户端取消工具调用也会取消 HeadlessMc 命令。

安装

从 GitHub Releases 下载最新发布版本：

文件	平台
headlessmc-mcp.jar	任何安装了 Java 25 或更高版本的平台：java -jar headlessmc-mcp.jar
headlessmc-mcp-windows-x64.exe	Windows x64
headlessmc-mcp-linux-x64、headlessmc-mcp-linux-arm64	Linux（例如 Ubuntu）x64 和 arm64
headlessmc-mcp-macos-arm64、headlessmc-mcp-macos-x64	Apple silicon 和 Intel 芯片的 macOS

构建

需要 JDK 25：

git clone --recurse-submodules https://github.com/headlesshq/headlessmc-mcp.git
cd headlessmc-mcp
./gradlew build
# -> build/headlessmc-mcp-<version>-runner.jar (includes the hmc-mcp-bridge mod)
# -> hmc-mcp-bridge/build/libs/hmc-mcp-bridge-<version>.jar

# native executable for the current platform, needs GraalVM 25 (or add -Dquarkus.native.container-build=true for Linux)
./scripts/build-native.sh
# -> build/headlessmc-mcp-<version>-runner

配置

属性	默认值	描述
hmc.mcp.specifics.version	3.0.1	要安装到客户端的 HMC-Specifics 版本。
hmc.mcp.specifics.url	GitHub releases	下载 URL 模板，包含 {tag}、{mc} 和 {loader}。
hmc.files.game-for-each-version	true	为每个版本单独设置游戏目录，避免模组文件夹冲突。
hmc.mcp.registry	<state dir>/headlessmc-mcp/instances	其他启动器注册游戏的位置；游戏也需设置此项。

所有 HeadlessMc 属性（hmc.*）也都可用作系统属性或写入 HeadlessMc 的配置文件。

hmc-mcp-bridge 模组会从系统属性中读取 hmc.mcp.token、hmc.mcp.portFile、hmc.mcp.host（127.0.0.1）、hmc.mcp.port（0，表示任意可用端口）、 hmc.mcp.registry 和 hmc.mcp.enabled（true）。如果未设置 hmc.mcp.token，它会注册游戏以供连接。

隐私和条款

MCP 服务在本地运行，不会发送遥测数据。请参阅隐私政策和使用条款。 HeadlessMc - MCP 不是 Minecraft 官方产品，也未获 Mojang 或 Microsoft 批准，且与两者无关联。