Minecraft Remote

MCP Minecraft Remote

本项目的灵感来自 arjunkmrm 开发的 mcp-minecraft。原项目仅支持连接本地 Minecraft 服务，本项目则从头开发，以新增对连接远程 Minecraft 服务的支持。

使用 MCP（Model Context Protocol）远程控制 Minecraft。

功能

• 通过 AI 助手连接并控制 Minecraft 玩家
• 在 Minecraft 世界中移动、挖矿、建造和互动
• 与服务中的其他玩家聊天
• 查看物品栏、玩家位置和服务信息
• 高级移动控制，包括跳跃、潜行和疾跑
• 实体互动，包括攻击和跟随
• 使用容器（箱子、熔炉等）
• 合成物品和与村民交易
• 详细的物品栏管理

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Minecraft 远程控制：

npx -y @smithery/cli install @nacal/mcp-minecraft-remote --client claude

快速安装（推荐）

npx -y @smithery/cli install mcp-minecraft-remote --client claude

按照 CLI 提示完成设置。

手动安装

# Install from npm
npm install -g mcp-minecraft-remote

# Or clone the repository
git clone https://github.com/nacal/mcp-minecraft-remote.git
cd mcp-minecraft-remote

# Install dependencies
npm install

# Build the project
npm run build

使用方法

与 Claude Desktop 搭配使用

1. 找到 Claude Desktop 配置文件：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 将 Minecraft Remote MCP 配置添加到配置文件中：

{
  "mcpServers": {
    "minecraft-remote": {
      "command": "npx",
      "args": ["-y", "mcp-minecraft-remote@latest"]
    }
  }
}

如果已全局安装：

{
  "mcpServers": {
    "minecraft-remote": {
      "command": "mcp-minecraft-remote"
    }
  }
}

如果已在本地克隆此仓库：

{
  "mcpServers": {
    "minecraft-remote": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-minecraft-remote/build/index.js"]
    }
  }
}

3. 保存文件并重启 Claude Desktop
4. 与 Claude 开始新的对话，并开始使用 Minecraft 控制命令

重要的服务要求

• 服务在线模式：Minecraft 服务的 server.properties 文件中必须设置 online-mode=false。这样机器人无需通过 Minecraft 会话服务进行身份验证即可连接。
• 如果使用需要身份验证的服务，连接时必须提供有效的高级账户凭据。

可用工具

核心功能

• connectToServer：使用指定的凭据连接到 Minecraft 服务
• disconnectFromServer：断开与 Minecraft 服务的连接
• sendChat：向服务发送聊天消息
• getServerInfo：获取已连接服务的信息

移动

• getPosition：获取玩家当前位置
• moveTo：移动到指定坐标
• moveControl：基本移动控制（前进、后退、左移、右移、跳跃、疾跑、潜行、停止）
• lookAt：让玩家朝向指定方向或坐标

世界互动

• digBlock：挖掘指定坐标处的方块
• placeBlock：在指定坐标处放置方块

物品栏管理

• checkInventory：基本物品栏检查
• inventoryDetails：获取物品栏中物品的详细信息
• equipItem：将物品栏中的物品装备到手部或盔甲栏位
• tossItem：丢弃物品栏中的物品

实体互动

• getNearbyPlayers：获取附近玩家列表
• getNearbyEntities：获取附近所有实体的列表
• attackEntity：攻击指定实体
• useOnEntity：对指定实体使用手持物品
• followEntity：跟随指定实体

容器互动

• openContainer：打开指定坐标处的容器（箱子、熔炉等）
• withdrawItem：从已打开的容器中取出物品
• depositItem：将物品放入已打开的容器
• closeContainer：关闭当前打开的容器

合成

• getRecipes：获取可用合成配方列表
• craftItem：使用可用材料合成物品

交易

• listTrades：列出附近村民提供的可用交易
• tradeWithVillager：与附近村民交易

示例提示词

基本控制

• “使用用户名 player1 连接到 Minecraft 服务端 play.example.com”
• “我当前在游戏中的位置是什么？”
• “将我移动到坐标 x=100、y=64、z=-200”
• “让我向前走 3 秒”
• “让我跳起来并冲向那座山”

背包与物品

• “详细查看我的背包里有什么”
• “把我的钻石剑装备到手上”
• “从我的背包中扔出 5 个泥土方块”

方块交互

• “挖掘坐标 x=10、y=65、z=20 处的方块”
• “在坐标 x=11、y=65、z=20 处放置一个石头方块”

实体交互

• “附近还有其他玩家吗？”
• “我周围 20 个方块内有哪些实体？”
• “攻击 ID 为 12345 的僵尸”
• “跟随名叫 Steve 的玩家”

容器使用

• “打开坐标 x=100、y=64、z=200 处的箱子”
• “从箱子里拿出 10 个铁锭”
• “把 5 个圆石放进箱子”
• “关闭容器”

合成与交易

• “我有哪些木镐合成配方？”
• “使用我背包里的木材合成 4 根木棍”
• “查看附近村民提供哪些交易”
• “与村民交易，获得 10 颗绿宝石”

沟通

• “在聊天中发送一条问候消息”
• “告诉大家我找到了钻石”

要求

• Node.js 18+
• 支持 MCP 的 AI 助手（例如 Claude）
• Minecraft Java 版服务端（版本 1.8 或更高版本）

注意：此工具已测试并验证，专门适用于原版 Minecraft 1.21。它可能也能在其他版本或模组服务端上运行，但不保证兼容性。

许可证

MIT