Skip to main content
Glama
Sign In
deenesjakoruzh
minecraft-mcp

minecraft-mcp

by soumyacodes007
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

⛏️ Minecraft MCP 服务器 — AI 驱动的 Minecraft 智能体

由 Soumyadeep（AI/ML 负责人）构建

这是什么？

这是一个由 模型上下文协议 (MCP) 驱动的 Minecraft AI 智能体。它将任何兼容 MCP 的 AI 客户端（Claude Desktop、Cursor、Kiro、Windsurf 等）直接连接到你的 Minecraft 世界，将 AI 变成一个功能齐全的游戏内机器人。

AI 可以移动、建造、合成、聊天，现在还可以通过单个命令——从原理图文件即时生成整个结构。

Related MCP server: Renge Bot

✨ 新功能 — 原理图构建器（核心亮点）

此分支最大的新增功能是 原理图构建系统 — 一套包含 3 个新的 MCP 工具，让 AI 能够使用 .schem / .schematic 文件在几秒钟内构建庞大、复杂的结构。

AI 不再需要繁琐地调用 place-block 数百次（速度慢、易出错、容易出错），现在它会：

  1. 检查其捆绑的库 中的原理图文件

  2. 解析文件 以了解其尺寸和方块

  3. 通过机器人发送一连串 /setblock 命令，在创造模式下即时构建整个结构 — 无需库存，无需寻路，不会失败

3 个新工具

工具

描述

list-schematics

列出服务器捆绑的所有 .schem 文件。AI 在尝试任何构建之前总是先调用此工具。

schematic-info

检查原理图文件 — 显示尺寸、填充百分比和顶部方块类型 — 而无需触碰世界。

build-schematic

使用快速的 /setblock 命令在给定的世界坐标处构建结构。接受短名称（"smallhouse1"）或完整路径。

支持的格式

格式

扩展名

备注

Sponge Schematic

.schem

✅ 主要格式（WorldEdit，现代）

MCEdit Schematic

.schematic

✅ 旧版格式，只读

NBT Structure

.nbt

✅ 原版 Minecraft 结构文件

AI 如何使用它

AI 被指示始终先检查捆绑的库。所以当你输入：

“在我附近建一座维京房屋”

AI 将会：

  1. 调用 list-schematics → 找到 viking-house1

  2. 调用 schematic-info("viking-house1") → 读取尺寸

  3. 调用 build-schematic("viking-house1", x, y, z) → 即时生成它

无需手动放置方块。没有幻觉几何图形。只需几秒钟，就能得到一个真实、由人类设计的结构。

🛠️ 完整工具参考

移动

工具

描述

get-position

获取机器人的当前世界坐标

move-to-position

寻路到特定坐标

look-at

让机器人看向坐标

jump

让机器人跳跃

move-in-direction

向某个方向移动一段时间

fly-to

直接飞向坐标

建造 (原理图)

工具

描述

list-schematics

★ 列出所有捆绑的原理图文件

schematic-info

检查原理图的元数据

build-schematic

从 .schem 文件即时构建结构

方块

工具

描述

place-block

在位置放置单个方块

dig-block

挖掘/破坏方块

get-block-info

获取坐标处方块的信息

find-blocks

查找附近给定类型的方块

库存与合成

工具

描述

list-inventory

列出机器人库存中的所有物品

find-item

查找特定物品

equip-item

装备物品

list-recipes

列出可合成的配方

craft-item

合成物品

get-recipe

获取详细的配方信息

can-craft

检查机器人是否可以合成某物品

smelt-item

在熔炉中烧炼物品

实体与聊天

工具

描述

find-entity

查找附近的实体

send-chat

发送游戏内聊天消息

read-chat

读取最近的聊天消息

detect-gamemode

检测当前游戏模式

🚀 设置指南

先决条件

  • Node.js ≥ 20.10.0

  • Git

  • Minecraft Java Edition (已在 1.21.x 上测试)

  • 兼容 MCP 的 AI 客户端 (Claude Desktop, Cursor, Kiro 等)

第 1 步 — 克隆并安装

git clone https://github.com/soumyadeo/minecraft-mcp-server.git
cd minecraft-mcp-server
npm install

第 2 步 — 构建

npm run build

这将把 TypeScript 编译为 dist/main.js。

第 3 步 — 添加原理图文件（可选但推荐）

将任何 .schem 文件放入项目根目录的 schematics/ 文件夹中：

minecraft-mcp-server/
  schematics/
    smallhouse1.schem       ← already included
    viking-house1.schematic ← already included
    my-castle.schem         ← add your own!

AI 将通过 list-schematics 自动发现它们。

第 4 步 — 配置你的 MCP 客户端

Claude Desktop

打开 File → Settings → Developer → Edit Config 并添加：

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "C:\\path\\to\\minecraft-mcp-server\\dist\\main.js",
        "--host", "localhost",
        "--port", "25565",
        "--username", "ClaudeBot"
      ]
    }
  }
}

Cursor / VS Code (mcp.json)

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "C:\\path\\to\\minecraft-mcp-server\\dist\\main.js",
        "--host", "localhost",
        "--port", "25565",
        "--username", "ClaudeBot"
      ],
      "type": "stdio"
    }
  }
}

将 C:\path\to\ 替换为你机器上的实际路径。

第 5 步 — 启动 Minecraft

  1. 启动 Minecraft Java Edition

  2. 打开或创建一个 单人世界

  3. 按 ESC → 对局域网开放

  4. 记下显示的端口号（通常是 25565）

  5. 在聊天中，给予机器人管理员权限：

    /op ClaudeBot

    ⚠️ /setblock 命令（原理图构建器使用）需要 管理员权限 才能工作

第 6 步 — 重启你的 AI 客户端并测试

完全重启你的 MCP 客户端（如有必要，从系统托盘关闭）。机器人应该会自动加入游戏。

测试提示词：

“检查有哪些可用的原理图，并在我当前的位置建造 smallhouse。”

📦 添加更多原理图

原理图库只是一个文件夹。要添加更多结构：

  1. 在线查找 .schem 文件：

  2. 将文件放入 minecraft-mcp-server/schematics/

  3. 重启 MCP 服务器

AI 会立即识别它们 — 无需更改代码。

⚙️ 服务器参数

参数

默认值

描述

--host

localhost

Minecraft 服务器主机名

--port

25565

Minecraft 服务器端口

--username

ClaudeBot

机器人的游戏内用户名

node dist/main.js --host localhost --port 25565 --username ClaudeBot

🏗️ 架构

src/
  main.ts                   — MCP server entry point, tool registration
  bot-connection.ts         — Mineflayer bot lifecycle management
  tool-factory.ts           — MCP tool registration wrapper
  tools/
    schematic-tools.ts      — ★ Schematic builder (new)
    block-tools.ts          — Block placement & digging
    position-tools.ts       — Movement & pathfinding
    inventory-tools.ts      — Inventory management
    crafting-tools.ts       — Recipe lookup & crafting
    furnace-tools.ts        — Smelting
    entity-tools.ts         — Entity detection
    chat-tools.ts           — In-game chat
    flight-tools.ts         — Flight control
    gamestate-tools.ts      — Game mode detection
schematics/                 — Bundled schematic file library
  smallhouse1.schem
  viking-house1.schematic

关键库：

分支并扩展自 yuniko-software/minecraft-mcp-server

🗺️ 路线图

  • [ ] mode: "bot_place" — 通过 mineflayer-builder 进行物理生存模式建造

  • [ ] 通过 @kleppe/litematic-reader 支持 .litematic 格式

  • [ ] search-and-build 工具 — 按关键字抓取和下载原理图

  • [ ] run-builder-script — 执行程序化构建脚本（用于金字塔、圆顶等）

  • [ ] 箱子和存储工具

  • [ ] 村民交易工具

  • [ ] 战斗与生存工具

🤝 贡献

欢迎提交 Pull Request！请参阅 CONTRIBUTING.md 获取指南。

📄 许可证

MIT — 请参阅 LICENSE

由 Soumyadip Debnath（AI/ML 负责人）构建和扩展 原始项目由 Yuniko Software 提供

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers