Minecraft Server Management Protocol MCP

Minecraft服务器管理协议MCP服务器

一 MCP（模型上下文协议） 服务器 提供通过以下方式管理Minecraft服务器的工具 Minecraft服务器管理协议.

特性

• 多服务器支持：连接并管理多个Minecraft服务器
• 综合工具：完全实现Minecraft服务器

管理协议

• 类型安全：用TypeScript编写，具有完整的类型定义
• 双向通信：基于WebSocket通信的高效JSON-RPC 2.0

需求

• 迪诺 2.0或更高
• minecraft服务器 1.21.9+启用管理服务器
• 在中配置的管理服务器 server.properties:

  management-server-enabled=true
  management-server-host=0.0.0.0
  management-server-port=9090
  management-server-tls-enabled=false

安装

1. 克隆此存储库：

   cd /home/bridger/git
   git clone  minecraft-server-management-protocol-mcp
   cd minecraft-server-management-protocol-mcp

1. 创建配置文件：

   cp config.json.example config.json

1. 编辑 config.json 您的服务器详细信息：

   {
     "servers": {
       "production": {
         "url": "ws://your-server-ip:9090",
         "secret": "your-40-character-secret-from-server.properties"
       }
     }
   }

使用Claude代码

添加MCP服务器

要将此服务器添加到Claude Code，请运行：

claude mcp add --scope user --transport stdio minecraft-server -- \
  deno run --unstable-net --allow-net --allow-read --allow-env \
  /home/bridger/git/minecraft-server-management-protocol-mcp/main.ts

备注：The --unstable-net 标志是必需的，因为此服务器使用Deno的 WebSocketStream API支持头，这是目前不稳定的功能。

卸下MCP服务器

如果需要删除或更新服务器配置：

claude mcp remove minecraft-server

然后用上面的命令重新添加它。

使用工具

添加后，您可以通过Claude Code与您的Minecraft服务器进行交互：

> How many players are on the production server?
> Kick player "Griefer123" from production with message "Banned for griefing"
> Get the server status for production
> Add "NewPlayer" to the allowlist on production
> Send a message "Server restarting in 5 minutes" to all players

可用工具

玩家管理

• minecraft_list_players -列出所有已连接的玩家
• minecraft_kick_player -用可选消息踢球员

服务器控件

• minecraft_server_status -获取服务器状态（版本、玩家、状态）
• minecraft_save_server -将世界保存到磁盘
• minecraft_stop_server -优雅地停止服务器
• minecraft_send_system_message -向玩家发送消息

允许列表管理

• minecraft_get_allowlist -获取所有已分配的玩家
• minecraft_add_to_allowlist -将玩家添加到满列表
• minecraft_remove_from_allowlist -从满名单中删除玩家
• minecraft_clear_allowlist -清除整个满网列表

更多工具（TODO）

计划使用以下工具类别：

• 禁令管理
• IP禁令管理
• 操作员管理
• 服务器设置（难度、最大玩家数、MOTD等）
• 游戏规则管理

配置

服务器配置格式

{
  "servers": {
    "": {
      "url": "ws://:
",
      "secret": ""
    }
  }
}

• server-name：您选择的友好名称（例如“制作”、“登台”）
• url：指向Minecraft管理服务器的WebSocket URL
• secret：The management-server-secret 从你的 server.properties

查找服务器密码

秘密就在你的Minecraft服务器上 server.properties 文件：

grep management-server-secret /var/lib/minecraft/server.properties

输出示例：

management-server-secret=ABCxyz123

发展

运行测试

deno test

本地运行

deno run --allow-net --allow-read --allow-env main.ts

添加新工具

1. 在中创建新文件 tools/ （例如。， tools/bans.ts)
2. 出口A registerBanTools(pool) 函数
3. 导入并添加到 allTools 在 main.ts

工具结构示例：

export function registerBanTools(pool: MinecraftConnectionPool) {
  return [
    {
      name: "minecraft_list_bans",
      description: "Get all banned players",
      inputSchema: {
        type: "object",
        properties: {
          server: { type: "string", description: "Server name" },
        },
        required: ["server"],
      },
      handler: async ({ server }: { server: string }) => {
        const bans = await pool.request(server, "minecraft:bans");
        return {
          content: [{ type: "text", text: JSON.stringify(bans, null, 2) }],
        };
      },
    },
  ];
}

建筑

main.ts                 # MCP server entry point
├── config.ts           # Configuration loader
├── websocket.ts        # WebSocket client & connection pool
├── types.ts            # TypeScript type definitions
└── tools/              # Tool implementations
    ├── players.ts
    ├── server.ts
    ├── allowlist.ts
    └── ...             # Add more tool files here

故障排除

“找不到配置文件”

确保您已创建 config.json 从 config.json.example 它在里面 项目根。

“WebSocket连接错误”

1. 验证您的Minecraft服务器是否正在运行
2. 检查一下 management-server-enabled=true 在server.properties中
3. 确保防火墙中的端口（9090）已打开
4. 验证URL格式： ws://host:port （不是 wss:// 除非启用了TLS）

“JSON-RPC错误-32601:找不到方法”

Minecraft服务器不支持这种方法。确保你在跑步 Minecraft 1.21.9或更高版本。

“请求超时”

服务器没有响应。检查：

1. 服务器正在运行且可访问
2. 管理服务器已启用并正在侦听
3. config.json和server.properties之间的秘密匹配

许可证

无许可（公共领域）

贡献

欢迎投稿！添加对更多Minecraft服务器管理的支持 协议方法：

1. 将类型添加到 types.ts 如有需要
2. 在中创建工具实现 tools/
3. 在中注册工具 main.ts
4. 更新此自述文件

参考文献

• Minecraft服务器管理协议
• 模型上下文协议
• JSON-RPC 2.0规范