Minecraft MCP服务器

minecraft mcp服务器

MCP（模型上下文协议）服务器，通过 Mineflayer 机器人支持 创造性的 和 生存 每种模式都有不同的工具集。bot在启动时使用环境变量中的配置自动连接——代理不传递任何连接参数。

通过以下方式进行沟通 标准 --将其插入任何MCP兼容客户端（Claude Desktop等）。

先决条件

• Node.js ≥ 20
• Minecraft Java版 服务器（香草、纸、蜘蛛等）
• 服务器必须位于 离线模式 (online-mode=false 在 server.properties)或者配置为机器人无需身份验证即可加入
• 创意模式：机器人需求 操作员权限 (/op <username>)用于命令工具(setblock, fill等等）
• 生存模式：不需要特殊的服务器权限

快速开始

npm install
npm run build

脚本

配置

所有配置均通过 环境变量机器人在启动时自动连接——代理从不传递连接参数。

MCP客户端集成

此服务器使用 stdio传输.通过设置模式和连接 env 在您的MCP客户端配置中。

创意模式（默认）

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/absolute/path/to/dist/main.js"],
      "env": {
        "MC_MODE": "creative",
        "MC_HOST": "localhost",
        "MC_PORT": "25565",
        "MC_USERNAME": "Builder"
      }
    }
  }
}

生存模式

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/absolute/path/to/dist/main.js"],
      "env": {
        "MC_MODE": "survival",
        "MC_HOST": "localhost",
        "MC_PORT": "25565",
        "MC_USERNAME": "Survivor"
      }
    }
  }
}

开发（无构建步骤）

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/src/main.ts"],
      "env": {
        "MC_MODE": "survival"
      }
    }
  }
}

工具

工具分为 常见的 （始终可用）， 仅限创意，以及 只生存 根据配置设置 MC_MODE.

常用工具（两种模式）

仅限创意的工具

可用时间： MC_MODE=creative。这些使用服务器命令并需要 操作员权限.

生存专用工具

可用时间： MC_MODE=survival。这些使用Mineflayer插件(开拓者, 收集块, 工具)对于自主机器人行为，不需要操作员权限。

为什么不 execute_command? 我们有意公开显式、类型化的工具，而不是原始命令passthrough。每个工具都会验证其输入并返回结构化结果，为代理提供更好的反馈并防止命令注入错误。

结构化工具输出

所有创意命令工具(setblock, fill, clone_area, give_item, teleport_to, set_time, set_weather, set_gamerule, summon_entity)返回结构化元数据以及人类可读的文本：

未确认、超时和失败的结果被报告为错误(isError: true)因此，代理可以自动检测问题并从中恢复。

fly_to 使用三阶段回退链并返回其他字段：

例子

创意模式

# Fly to a build site
fly_to(x: 100, y: 80, z: 200)

# Place a single diamond block
setblock(x: 100, y: 64, z: 200, block: "diamond_block")

# Build a 10×1×10 stone platform
fill(x1: 0, y1: 63, z1: 0, x2: 10, y2: 63, z2: 10, block: "stone")

# Hollow out a cube of glass
fill(x1: 0, y1: 64, z1: 0, x2: 10, y2: 74, z2: 10, block: "glass", mode: "hollow")

# Give yourself 64 diamonds
give_item(item: "diamond", count: 64)

# Set daytime
set_time(value: "day")

生存模式

# Navigate to coordinates
go_to(x: 100, y: 64, z: 200)

# Mine a block (auto-selects best tool)
dig_block(x: 100, y: 63, z: 200)

# Collect 10 oak logs nearby
collect_block(blockName: "oak_log", count: 10)

# Craft planks from logs
craft_item(itemName: "oak_planks", count: 4)

# Equip a sword
equip_item(itemName: "stone_sword", destination: "hand")

故障排除

权限被拒绝（创意模式）

机器人需要服务器上的操作员权限：

/op <bot_username>

创意指挥工具(setblock, fill等）返回 isError: true 与类别 "permission_denied" 如果bot缺乏权限。

未知命令

当命令无效或拼写错误时返回。检查：

• 正确的块ID（例如。 stone, diamond_block，不 Stone)
• 有效坐标范围
• 正确的命令语法

无响应/超时

创意命令工具等待 5秒 用于服务器反馈。超时意味着：

• 该命令可能已执行，但未产生可识别的响应
• 服务器可能出现延迟

工具返回 category: "timeout" 和 timedOut: true，并被视为错误(isError: true)因此代理可以决定如何继续。

fly_to 失败

fly_to 自动按顺序尝试三种策略：

1. 直飞 — bot.creative.flyTo() 到目标
2. 弧形飞行 --上升到当前/目标Y上方的动态高度，水平飞行，然后下降（避开障碍物）
3. 远程端口回退 — /tp 如果两种飞行方法都失败，则发出命令

检查 method 在回复中，看看使用了哪种策略。如果这三个都失败， executionConfirmed 是 false 和 isError 是 true.

连接问题

• 验证Minecraft服务器是否正在运行且可访问
• 检查 online-mode=false 在 server.properties 用于离线模式机器人
• 确保端口正确（默认值： 25565)
• 如果服务器已满或用户名已在使用中，机器人无法连接
• 检查 MC_AUTO_CONNECT 未设置为 false 如果您希望自动连接