让 Claude、Cursor 和 VS Code Copilot 等 AI 助手通过 Model Context Protocol 运行你的 Minecraft 服务器:控制台命令、配置文件、日志和插件 jar。
询问“为什么服务器在晚上 8 点卡顿?”、“为建筑者设置 LuckPerms 权限组”或“修复 Essentials 配置中的 YAML 错误”,AI 会自行读取日志、编辑文件并执行命令。
功能
- 带有真实输出的控制台命令。 Vanilla 和插件命令返回它们在控制台中打印的完全相同的内容,包括响应较慢的插件(如 LuckPerms)。
- 文件操作。 读取、写入、追加和删除服务器文件夹中的文件,分块读取大文件,以及上传或下载二进制文件(如 jar)。
- 服务器概览。 一次调用即可获取版本、玩家数量、TPS 和 MSPT (Paper)、内存使用情况、世界和插件信息。
- 日志。
latest.log 的末尾部分,可选择仅包含特定关键词(如 ERROR)的行。
- 默认安全。 首次启动时生成随机令牌,以恒定时间进行检查,持续尝试猜测的地址将被锁定。无法访问服务器文件夹以外的任何内容。
- 审计日志。 每次工具调用都会记录到控制台,包含命令或路径(绝不包含文件内容)。
- 兼容所有 MCP 客户端。 支持当前客户端的可流式 HTTP (
/mcp),以及较旧的 SSE 传输 (/sse)。
- 轻量级。 无内置 Web 服务器或库依赖。jar 包大小不足 100 KB。
- 支持 1.20 至 26.x 版本,适用于 Paper、Purpur、Spigot 和 Bukkit。
工具
| 工具 |
功能说明 |
execute_command |
运行控制台命令并获取其输出 |
server_info |
版本、玩家、TPS/MSPT、内存、在线时长、世界 |
list_plugins |
已安装插件及其版本、状态和作者 |
get_logs |
latest.log 的最后几行,可选择过滤 |
list_directory |
列出文件和文件夹及其大小 |
read_file |
读取文本文件,可选择读取指定范围的行 |
write_file |
创建、覆盖或追加文本文件 |
read_file_base64 |
将任意文件以下载 base64 格式 |
write_file_base64 |
上传二进制文件,例如插件 jar |
delete_file |
删除单个文件 |
可在配置文件中关闭其中任何工具,例如使 AI 处于只读模式。
安装
- 将 jar 放入
plugins/ 目录并重启。插件监听端口 25374。
- 在服务器控制台中运行
dmcp token 以获取访问令牌。
- 确保运行 AI 客户端的计算机可以访问端口 25374(在主机的防火墙中开放该端口,或参见下方的“不需要额外端口?”部分)。
- 将服务器添加到你的 AI 客户端。替换
SERVER-IP 和 TOKEN:
Claude Code
claude mcp add --transport http minecraft http://SERVER-IP:25374/mcp --header "Authorization: Bearer TOKEN"
Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"minecraft": {
"url": "http://SERVER-IP:25374/mcp",
"headers": { "Authorization": "Bearer TOKEN" }
}
}
}
VS Code (.vscode/mcp.json)
{
"servers": {
"minecraft": {
"type": "http",
"url": "http://SERVER-IP:25374/mcp",
"headers": { "Authorization": "Bearer TOKEN" }
}
}
}
Claude Desktop (claude_desktop_config.json,需要 Node.js)
{
"mcpServers": {
"minecraft": {
"command": "npx",
"args": ["mcp-remote", "http://SERVER-IP:25374/mcp", "--allow-http", "--header", "Authorization:${AUTH}"],
"env": { "AUTH": "Bearer TOKEN" }
}
}
}
仅支持较旧 SSE 传输的客户端可使用 http://SERVER-IP:25374/sse 并使用相同的头部信息。
命令
所有命令都需要 developermcp.admin 权限(默认为 op)。/dmcp 是 /developermcp 的简写。
| 命令 |
功能说明 |
/dmcp status |
查看 MCP 服务器是否正在运行、其地址及已连接的客户端 |
/dmcp reload |
重新加载 config.yml |
/dmcp token |
显示访问令牌(仅限控制台) |
/dmcp token regenerate |
生成新令牌;旧令牌立即失效 |
配置
config.yml
server:
# 0.0.0.0 = 所有网络接口。如果 AI 客户端在同一台机器上运行,请使用 127.0.0.1。
host: "0.0.0.0"
port: 25374
# 首次启动时生成。在控制台中使用 "dmcp token" 显示它。
token: ""
tools:
# 禁用工具,例如 [execute_command, write_file_base64, delete_file]
disabled: []
# read_file 和 read_file_base64 允许返回的最大文件大小,单位为兆字节 (1-64)。
maxReadSizeMb: 8
# 将每次工具调用记录到控制台(记录工具和命令或路径,绝不记录文件内容)。
logCalls: true
安全性
此插件赋予持有令牌者对你服务器的完全控制权:他们可以运行任何控制台命令并更改服务器文件夹中的任何文件。
- 保持令牌机密。如果泄露,请运行
dmcp token regenerate。
- 流量为纯 HTTP。在不信任的网络上,请将端口置于 VPN、SSH 隧道或 HTTPS 反向代理之后,或者当 AI 在同一台机器上运行时绑定到
127.0.0.1。
- AI 助手可能会犯错。请保留备份,并关闭你不需要的工具。
不需要额外端口?
如果你的主机无法打开其他端口,可以使用隧道服务,如 playit.gg:创建指向 127.0.0.1:25374 的 TCP 隧道,并在客户端配置中使用 playit 提供的地址。
从 1.x (MCPMinecraft) 升级
1.x 版本名为 MCPMinecraft。删除旧的 mcp-minecraft-*.jar 并添加新的。你的端口和令牌会自动从 plugins/MCPMinecraft 复制。如果你仍在使用 1.x 的默认令牌,系统将生成一个新的随机令牌:运行 dmcp token 并更新你的客户端。带有 ?token= 参数的旧 SSE URL 仍可正常工作,但推荐使用 Authorization 头部。
支持
错误与建议:GitHub issues 或 Discord。
Let AI assistants like Claude, Cursor and VS Code Copilot run your Minecraft server: console commands, config files, logs and plugin jars, through the Model Context Protocol.
Ask "why did the server lag at 8pm?", "set up LuckPerms groups for builders" or "fix the YAML error in my Essentials config", and the AI reads the logs, edits the files and runs the commands itself.
Features
- Console commands with real output. Vanilla and plugin commands return exactly what they print in the console, including plugins that answer late such as LuckPerms.
- Files. Read, write, append and delete files in the server folder, read big files in parts, and upload or download binary files such as jars.
- Server overview. Version, players, TPS and MSPT (Paper), memory, worlds and plugins in one call.
- Logs. The end of
latest.log, optionally only lines containing a word like ERROR.
- Secure by default. A random token is generated on first start, it is checked in constant time, and addresses that keep guessing get locked out. Nothing outside the server folder is reachable.
- Audit log. Every tool call is logged to the console with the command or path (never file contents).
- Works with every MCP client. Streamable HTTP (
/mcp) for current clients, plus the older SSE transport (/sse).
- Tiny. No bundled web server or libraries. The jar is under 100 KB.
- 1.20 to 26.x on Paper, Purpur, Spigot and Bukkit.
Tools
| Tool |
What it does |
execute_command |
Run a console command and get its output |
server_info |
Version, players, TPS/MSPT, memory, uptime, worlds |
list_plugins |
Installed plugins with version, status and authors |
get_logs |
Last lines of latest.log, optionally filtered |
list_directory |
Files and folders with sizes |
read_file |
Read a text file, optionally a range of lines |
write_file |
Create, overwrite or append to a text file |
read_file_base64 |
Download any file as base64 |
write_file_base64 |
Upload a binary file, e.g. a plugin jar |
delete_file |
Delete a single file |
Switch off any of them in the config, for example to make the AI read-only.
Setup
- Put the jar in
plugins/ and restart. The plugin listens on port 25374.
- Run
dmcp token in the server console to get your access token.
- Make sure port 25374 is reachable from the computer running your AI client (open it on your host or firewall, or see "No extra port?" below).
- Add the server to your AI client. Replace
SERVER-IP and TOKEN:
Claude Code
claude mcp add --transport http minecraft http://SERVER-IP:25374/mcp --header "Authorization: Bearer TOKEN"
Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"minecraft": {
"url": "http://SERVER-IP:25374/mcp",
"headers": { "Authorization": "Bearer TOKEN" }
}
}
}
VS Code (.vscode/mcp.json)
{
"servers": {
"minecraft": {
"type": "http",
"url": "http://SERVER-IP:25374/mcp",
"headers": { "Authorization": "Bearer TOKEN" }
}
}
}
Claude Desktop (claude_desktop_config.json, needs Node.js)
{
"mcpServers": {
"minecraft": {
"command": "npx",
"args": ["mcp-remote", "http://SERVER-IP:25374/mcp", "--allow-http", "--header", "Authorization:${AUTH}"],
"env": { "AUTH": "Bearer TOKEN" }
}
}
}
Clients that only speak the older SSE transport can use http://SERVER-IP:25374/sse with the same header.
Commands
All need developermcp.admin (op by default). /dmcp is short for /developermcp.
| Command |
What it does |
/dmcp status |
Whether the MCP server is running, its address and connected clients |
/dmcp reload |
Reload config.yml |
/dmcp token |
Show the access token (console only) |
/dmcp token regenerate |
Make a new token; the old one stops working right away |
Configuration
config.yml
server:
# 0.0.0.0 = every network interface. Use 127.0.0.1 if the AI client runs on the same machine.
host: "0.0.0.0"
port: 25374
# Generated on first start. Show it with "dmcp token" in the console.
token: ""
tools:
# Switch off tools, e.g. [execute_command, write_file_base64, delete_file]
disabled: []
# Largest file read_file and read_file_base64 will return, in megabytes (1-64).
maxReadSizeMb: 8
# Log each tool call to the console (tool and command or path, never file contents).
logCalls: true
Security
This plugin gives whoever holds the token full control of your server: they can run any console command and change any file in the server folder.
- Keep the token secret. If it leaks, run
dmcp token regenerate.
- Traffic is plain HTTP. On an untrusted network, put the port behind a VPN, an SSH tunnel or an HTTPS reverse proxy, or bind to
127.0.0.1 when the AI runs on the same machine.
- AI assistants make mistakes. Keep backups, and switch off tools you don't need.
No extra port?
If your host can't open another port, use a tunnel such as playit.gg: create a TCP tunnel to 127.0.0.1:25374 and use the address playit gives you in your client config.
Upgrading from 1.x (MCPMinecraft)
Version 1.x was called MCPMinecraft. Delete the old mcp-minecraft-*.jar and add the new one. Your port and token are copied from plugins/MCPMinecraft automatically. If you were still using the default token from 1.x, a new random one is generated: run dmcp token and update your client. Old SSE URLs with ?token= keep working, but the Authorization header is recommended.
Support
Bugs and ideas: GitHub issues or Discord.
评论 0
登录后参与评分
还没有评论,来抢沙发吧