Command MCP
将你的 Minecraft 服务器暴露为一个 MCP(Model Context Protocol)服务器,以便 Claude 等 AI 助手能够远程操作你的服务器:搜索并运行命令、使用游戏内的 Tab 补全功能,以及构建数据包——所有这些都通过标准的 MCP 客户端完成。
专为 Fabric 构建,零额外依赖:MCP 服务器使用 Streamable HTTP 传输(POST/GET/DELETE /mcp),基于 JSON-RPC 2.0 协议,实现依赖于 JDK 内置的 HttpServer 和 Minecraft 自带的 Gson。
功能特性
- 命令访问 — 搜索已注册的命令(原版及模组命令),在主线程上以控制台身份(OP 等级 4)执行命令并捕获输出,运行只读查询,获取与游戏内行为一致的 Tab 补全建议。
- 数据包工作流 — 检查服务器信息(版本、
pack_format、目录结构),列出数据包,读取/写入/删除数据包文件,并通过完整的错误报告进行重载(包括 .mcfunction 语法错误、JSON 错误、不兼容的 pack_format)。
- 会话管理 — 基于
Mcp-Session-Id 的会话,支持空闲超时、SSE 保活流,以及可选的 Authorization: Bearer 令牌认证。
- 游戏内感知 — 当 AI 客户端连接或断开时,发送聊天通知。
- 安全默认设置 — 仅绑定到
127.0.0.1;可禁用数据包文件写入。
要求
- Minecraft
1.20.1
- Fabric Loader
>= 0.19.3
- Fabric API
- Java
>= 17
快速开始
- 将模组 jar 放入
mods 文件夹并启动游戏/服务器。
- MCP 服务器会自动启动:
- 专用服务器:默认启用。
- 单人游戏 / 客户端:默认禁用;在配置文件中设置
enabled=true 以开启。
- 将你的 MCP 客户端指向
http://127.0.0.1:8123/mcp(Streamable HTTP)。
Claude Desktop 配置示例:
{
"mcpServers": {
"minecraft": {
"type": "http",
"url": "http://127.0.0.1:8123/mcp",
"headers": {
"Authorization": "Bearer <your-token>"
}
}
}
}
配置
配置文件:config/command-mcp.properties(首次启动时自动生成默认配置)。
| 选项 |
默认值 |
描述 |
enabled |
专用服务器上为 true,客户端环境中为 false |
游戏启动时是否启动 MCP HTTP 服务器。 |
host |
127.0.0.1 |
绑定地址。除非你清楚自己在做什么,否则请保持 127.0.0.1。 |
port |
8123 |
绑定端口(0 = 系统自动分配)。 |
authToken |
(空) |
当非空时,请求必须发送 Authorization: Bearer <token> 或 X-Auth-Token: <token>。 |
datapackWrite |
true |
允许 write_datapack_file / delete_datapack_file 修改世界的 datapacks 文件夹。 |
MCP 工具
| 工具 |
描述 |
list_commands |
按名称/别名/帮助文本搜索已注册命令;返回使用模板。 |
execute_command |
以控制台身份(OP 等级 4)执行命令并返回捕获的输出。 |
query_command |
运行只读查询命令(如 /list、/time query daytime、/data get 等)。 |
get_command_completions |
针对部分命令的 Tab 补全建议,匹配游戏内行为。 |
get_server_info |
Minecraft 版本、pack_format、数据包目录结构、已加载的模组。 |
list_datapacks |
世界文件夹中的数据包:类型、启用状态、提供的命名空间。 |
read_datapack_file |
读取世界 datapacks 文件夹内的 UTF-8 文本文件。 |
write_datapack_file |
创建/覆盖数据包文件;自动创建 pack.mcmeta 和父目录。 |
delete_datapack_file |
删除 datapacks 文件夹内的文件或目录。 |
reload_datapacks |
重载数据包并等待,然后报告成功或捕获到的错误/警告。 |
安全须知
- 服务器以 OP 等级 4 执行命令 —— 请将 MCP 访问视为拥有完整的服务器权限。
- 默认情况下,服务器仅监听
127.0.0.1。如果你通过网络暴露它,请务必设置 authToken。
- 设置
datapackWrite=false 可使数据包工具仅处于只读模式。
开发
./gradlew build
构建后的 jar 包位于 build/libs/ 中。
许可证
根据 GPL-3.0 license 发布。如果你在项目中使用了此代码,你的项目也必须在兼容的许可证下开源。
Command MCP
Expose your Minecraft server as an MCP (Model Context Protocol) server, so AI assistants such as Claude can operate your server remotely: search and run commands, use in-game Tab completion, and build datapacks — all through a standard MCP client.
Built for Fabric with zero additional dependencies: the MCP server uses Streamable HTTP transport (POST/GET/DELETE /mcp) with JSON-RPC 2.0, implemented on the JDK's built-in HttpServer and Minecraft's bundled Gson.
Features
- Command access — search registered commands (vanilla and mods), execute commands as console (OP level 4) on the server main thread with captured output, run read-only queries, and get Tab-completion suggestions that match in-game behavior.
- Datapack workflow — inspect server info (version,
pack_format, directory layout), list datapacks, read/write/delete datapack files, and reload with full error reporting (.mcfunction syntax errors, JSON errors, incompatible pack_format).
- Session management —
Mcp-Session-Id based sessions with idle timeout, SSE keepalive streams, and optional Authorization: Bearer token auth.
- In-game awareness — chat notifications when an AI client connects or disconnects.
- Safe defaults — binds to
127.0.0.1 only; datapack file writes can be disabled.
Requirements
- Minecraft
1.20.1
- Fabric Loader
>= 0.19.3
- Fabric API
- Java
>= 17
Getting Started
- Drop the mod jar into your
mods folder and start the game/server.
- The MCP server starts automatically:
- Dedicated servers: enabled by default.
- Single-player / client: disabled by default; set
enabled=true in the config to turn it on.
- Point your MCP client at
http://127.0.0.1:8123/mcp (Streamable HTTP).
Example Claude Desktop configuration:
{
"mcpServers": {
"minecraft": {
"type": "http",
"url": "http://127.0.0.1:8123/mcp",
"headers": {
"Authorization": "Bearer <your-token>"
}
}
}
}
Configuration
Config file: config/command-mcp.properties (created with defaults on first launch).
| Option |
Default |
Description |
enabled |
true on dedicated servers, false in client environments |
Whether the MCP HTTP server starts with the game. |
host |
127.0.0.1 |
Bind address. Keep 127.0.0.1 unless you know what you are doing. |
port |
8123 |
Bind port (0 = system-assigned). |
authToken |
(empty) |
When non-empty, requests must send Authorization: Bearer <token> or X-Auth-Token: <token>. |
datapackWrite |
true |
Allow write_datapack_file / delete_datapack_file to modify the world's datapacks folder. |
MCP Tools
| Tool |
Description |
list_commands |
Search registered commands by name/alias/help text; returns usage templates. |
execute_command |
Execute a command as console (OP level 4) and return captured output. |
query_command |
Run a read-only query command (/list, /time query daytime, /data get, ...). |
get_command_completions |
Tab-completion suggestions for a partial command, matching in-game behavior. |
get_server_info |
Minecraft version, pack_format, datapack directory layout, loaded mods. |
list_datapacks |
Datapacks in the world folder: type, enabled state, provided namespaces. |
read_datapack_file |
Read a UTF-8 text file inside the world's datapacks folder. |
write_datapack_file |
Create/overwrite a datapack file; auto-creates pack.mcmeta and parent directories. |
delete_datapack_file |
Delete a file/directory inside the datapacks folder. |
reload_datapacks |
Reload datapacks and wait, then report success or captured errors/warnings. |
Security Notes
- The server executes commands at OP level 4 — treat MCP access as full server access.
- By default the server only listens on
127.0.0.1. If you expose it over a network, always set an authToken.
- Set
datapackWrite=false to keep the datapack tools read-only.
Development
./gradlew build
The built jar lands in build/libs/.
License
Released under the GPL-3.0 license. If you use this code in your project, your project must also be open-sourced under a compatible license.
评论 0
登录后参与评分
还没有评论,来抢沙发吧