Skip to main content
Glama
gjlmotea

BlockHand

by gjlmotea

BlockHand(積木之手)— Minecraft Education MCP

讓 AI 在 Minecraft Education Edition 裡長出手腳:動作(Agent 走位、挖掘、放置、耕種、搬運)、眼睛(感測方塊、查詢座標、訂閱遊戲事件)、造物(十種幾何形狀與逐格藍圖)。

透過 Minecraft Education 官方文件化的 /wsserver 連線命令(/connect 是 alias)操作,不注入行程、不改遊戲檔案、不用畫面辨識。連線命令是官方介面;後續 WebSocket 訊息協定並沒有公開穩定性保證,因此遊戲改版後仍需重新驗證。

  • 42 個工具、2 份 resource

  • 216 項單元與整合測試、1 支不需開遊戲的 stdio/程序生命週期 smoke、1 支真機 live 驗證

  • 不需要任何帳號、token 或祕密;MCP runtime 只綁 loopback,不寫遊戲檔或 artifact


1. 三步上手

步驟一:在每台機器安裝與建置

cd /你的路徑/minecraft-edu
corepack pnpm install --frozen-lockfile
corepack pnpm run build

Node 必須是專案 .nvmrc 指定的 22.23.1,pnpm 由 Corepack 固定為 11.17.0。Windows 與 Mac 都要在本機安裝依賴;不要把另一個作業系統的 node_modules 複製過來。Minecraft Education 目前在 Mac 的最低需求是 macOS 14

步驟二:在該機登記一次 MCP

支援 Codex/Claude Code/Gemini CLI/Grok CLI,Windows 與 macOS 皆同。

先取得兩個絕對路徑

註冊時必須用絕對路徑,不能只寫 node。桌面版 AI 工具是由 Finder/檔案總管啟動的,讀不到你 shell 裡的 nvm、Homebrew 或 PATH;寫 node 在終端機測得過,換成桌面版就會啟動失敗,而且錯誤訊息通常只說「server 沒回應」,很難查。

macOS:

node -p "process.execPath"   # Node 絕對路徑
pwd                          # 專案絕對路徑(在 minecraft-edu 目錄下執行)

Windows(PowerShell):

node -p "process.execPath"
(Get-Location).Path

下面用 <NODE> 代表 Node 絕對路徑、<REPO> 代表專案絕對路徑。伺服器進入點固定是 <REPO>/dist/index.js(Windows 寫成 <REPO>\dist\index.js)。路徑含空白時整段要加引號。

用安裝器(四家都支援,建議)

corepack pnpm run setup:codex     # 或 setup:claude / setup:gemini / setup:grok
corepack pnpm run doctor          # 加 --client=claude 等可診斷其他家

安裝器不是只把指令寫進設定檔,它會:

  • 自動填入這台機器的絕對 Node 路徑,不依賴桌面程式能否讀到 nvm、Homebrew 或 shell PATH。

  • 先跑一次真正的 MCP initialize(用即將寫入的 command/args/env),確認 42 個工具都在,才動任何持久設定。舊 dist、錯誤 launcher、不可執行的 Node 都會在寫入之前就失敗。

  • 已正確登記時什麼都不做,重跑安全。

  • 同名但不相容時停下並列出差異,不自動 remove/add,避免覆寫別人的 timeout、tool policy 或另一個 clone 的設定。

  • 只透過各家官方 mcp addmcp remove 子指令寫入,不手改設定檔——那會繞過各家自己的 schema 驗證與 scope 解析。

移除用 corepack pnpm run uninstall:codex(或 uninstall:claude 等)。同樣有防誤刪:不是這份工作樹可辨識的 entry 就拒絕。

各家寫入位置與重啟需求:

Client

寫入

之後

Codex

~/.codex/config.toml

完全退出並重啟;桌面版/CLI/IDE 共用

Claude Code

~/.claude.json(user scope)

重開 session

Gemini CLI

~/.gemini/settings.json(user scope)

重開 CLI

Grok CLI

~/.grok/config.toml

重開 CLI

讀取策略有差異:Codex 與 Grok 有 mcp list --json,直接用機器可讀輸出。Claude Code 與 Gemini 的 list 只有人類可讀文字且不含 env,無法據以判斷相容性,所以改唯讀它們官方 CLI 剛寫入的設定檔。寫入永遠走 CLI。

手動指令(不想用安裝器時)

指令等價,但絕對路徑要自己填,也沒有前置的 initialize 驗證與覆寫保護。

codex  mcp add minecraft-edu --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js
claude mcp add minecraft-edu --scope user --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js
gemini mcp add minecraft-edu <NODE> <REPO>/dist/index.js --scope user --env MINECRAFT_EDU_WS_PORT=19131
grok   mcp add minecraft-edu --scope user --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js

三個容易踩的差異:

  • Gemini 的 command 與 args 是位置參數,接在名稱後面,沒有 -- 分隔。

  • Gemini 的預設 scope 是 project,要全域可用必須明寫 --scope user

  • Claude 的預設 scope 是 local(只在目前目錄生效);--scope project 會寫進專案根的 .mcp.json,可隨 repo 分享,整班共用時用這個

手動編設定檔(安裝器失效時的後備)

Claude Code 與 Gemini CLI 用 JSON:

{
  "mcpServers": {
    "minecraft-edu": {
      "command": "<NODE>",
      "args": ["<REPO>/dist/index.js"],
      "env": { "MINECRAFT_EDU_WS_PORT": "19131" }
    }
  }
}

Codex 與 Grok CLI 用 TOML:

[mcp_servers.minecraft-edu]
command = "<NODE>"
args = ["<REPO>/dist/index.js"]
env = { MINECRAFT_EDU_WS_PORT = "19131" }

Windows 補充

  • Node 絕對路徑通常是 C:\Program Files\nodejs\node.exe,用 nvm-windows 則像 C:\Users\<你>\AppData\Roaming\nvm\v22.23.1\node.exe

  • JSON 設定檔裡的反斜線要跳脫:"C:\\Program Files\\nodejs\\node.exe"。TOML 可以改用單引號字面字串:command = 'C:\Program Files\nodejs\node.exe'

  • Minecraft Education 若是 Microsoft Store 的 UWP 版,loopback 會被 Windows 應用程式隔離擋住,需要額外的 CheckNetIsolation LoopbackExempt 豁免(見第 8 節)。

登記後

完全退出並重啟該 AI 工具——桌面版要真的結束程式,不是關掉視窗。然後用 doctor 確認(不碰 Minecraft、不改設定):

corepack pnpm run doctor

它會檢查 Node 版本、build 產物、平台需求、登記狀態,並用實際登記的 command/args/env 再跑一次 MCP initialize,避免設定指向失效 Node 卻假綠。加 --json 可得結構化輸出。也可以直接問各家 CLI:

codex mcp list
claude mcp list
gemini mcp list
grok mcp list

或直接叫 AI 呼叫 mc_status,能回傳 connectCommand 就代表 server 起得來。

每台機器都要各自登記一次:Windows 筆電、Mac、另一台電腦的 Node 與專案絕對路徑都不同,不能互相複製設定。同一台機器上,同一個工具的桌面版/CLI/IDE 共用同一份設定。

步驟三:在遊戲裡手動連進來

corepack pnpm run connect

這個相容入口只顯示操作方式,不會開 Minecraft、不會切換前景視窗,也不會模擬鍵盤。Windows PowerShell 自動輸入功能已移除;Mac 也不加入 AppleScript 自動化。

方向很容易搞反:遊戲是連出來的一方,MCP server 是被連的一方。

  1. 在目前的 AI 對話中呼叫 mc_status,複製它回傳的 connectCommand

  2. 開 Minecraft Education,進入一個世界(停在主選單沒有用)。

  3. 世界必須開啟 Cheats,操作者需有 Admin/OP 權限。

  4. 在聊天列手動輸入,例如:

/connect 127.0.0.1:19131

看到 Connection established 就完成了。之後對 AI 說「幫我在前面蓋一顆空心玻璃球」即可。

要重連時不必重打整串:在聊天列按 T 開啟,再按 叫回上一條指令,然後 Enter。

早期版本有一個「閒置約 60 秒必斷線」的 bug:心跳只認 WebSocket pong frame,但 Bedrock/Education 的客戶端從不回 pong,導致健康的連線被自己的心跳終止。現已修正(改以任何進來的封包判定活性,並輔以應用層探測),閒置不應再造成斷線。若仍會斷,先確認你跑的是重新 build 過的 dist/

不要固定背 19131:桌面版、CLI、IDE 或多個 task 同時啟動時,後開的 MCP 可能取得不同空閒埠。永遠使用目前要操作的那個 task回報的指令。


Related MCP server: Minecraft MCP Bot

2. 真機驗證

先做不開遊戲的安全診斷:

corepack pnpm run doctor
# 機器可讀版本
corepack pnpm blockhand doctor --json

doctor 不修改持久設定、不啟動 Minecraft;它會短暫建立隔離的 loopback socket,驗證 launcher、42 tools、2 resources、stdio EOF、監聽埠釋放,並以 Codex 實際登記的 command/args/env 再完成一次 initialize,避免設定指向失效 Node 卻假綠。

遊戲開著、世界已載入、作弊已開之後:

cd gjlmotea/vibe/mcp/minecraft-edu && corepack pnpm run live

腳本會印出要輸入的 /connect,等你連上,然後走完一條完整路徑並逐項回報 PASS/FAIL:連線 → 讀玩家座標 → 遊戲內發話 → 設定時間 → 召喚 Agent → 感測 → 走 L 形路徑 → 預覽建造 → 蓋空心玻璃球 → 回頭驗證方塊真的存在 → 藍圖合併 → 訂閱並收事件 → 政策閘門 → 清除示範建築。

遊戲改版之後

讀方塊(mc_read_block)靠的是 testforblock 失敗訊息的文字格式,那個格式沒有任何官方穩定性保證。Minecraft Education 默默自動更新改了文案、或遊戲語言換成不是繁中/簡中/英文,這條路就會失效。

失效的樣子是安靜的:工具不會壞掉,只會開始說「讀不出來」。所以本專案刻意不把它做成每次 live 都跑的例行檢查——例行檢查會養成看到綠燈就放心的習慣,而真正需要判斷的時機是「行為變得可疑的當下」,不是每週固定跑的那一次。

改成在需要時主動判斷:

mc_verify_reading  { position: 任一座標 }

它最多送兩條指令、完全不寫入世界,回傳 parseable

  • true → 解析路徑正常,mc_read_block 的結果可信。

  • false協定已漂移。此時 mc_read_block 一律回錯誤而不是 null(見第 3 節),所以不會有人把「讀不出來」誤當成「那裡是空的」。回傳的 raw 是遊戲的原始訊息,拿它去比對 src/domain/block-report.tsPATTERNS 就知道要補哪一條。

三個會讓你想跑它的訊號:

  1. mc_read_block 開始回錯誤,但你人在遊戲裡看得到那格明明有東西。

  2. 遊戲剛更新過,而你接下來要做任何依賴讀取的事(批改、對稱分析)。

  3. 換了遊戲語言。

server instructions 裡也放了同一條線索,所以 AI 在行為可疑時會自己找到這支工具,不需要你記得提醒它。

預設會把示範建築填回 air,不在世界裡留垃圾。想留下來看:

cd gjlmotea/vibe/mcp/minecraft-edu && node scripts/live-check.mjs --keep

不需要開遊戲的驗證(型別、測試、build、stdio 握手、STDIN 關閉釋放連接埠與占埠失敗一次跑完):

cd gjlmotea/vibe/mcp/minecraft-edu && corepack pnpm run verify

3. 工具面

連線與後備(4)

工具

用途

mc_status

橋接狀態、連線指令、已訂閱事件、累計指令數。任何失敗先查這個

mc_await_connection

阻塞等待遊戲連入(單次上限 120 秒)

mc_run_command

單行 raw slash 指令;沒有專用工具時的後備

mc_run_commands

依序執行多條 raw 指令

Agent — 手腳(10)

工具

用途

mc_agent_create

召喚 Agent

mc_agent_move

往指定方向走 N 格

mc_agent_turn

左右轉,每次 90 度

mc_agent_teleport

把走丟的 Agent 叫回玩家身邊

mc_agent_act

attack/destroy/till,可連續

mc_agent_place

從背包槽放置方塊

mc_agent_collect

撿取掉落物

mc_agent_inventory

count/space/detail/drop/dropAll/transfer

mc_agent_sense

inspect/inspectData/detect/detectRedstone —— Agent 的眼睛

mc_agent_program

一次送出一整段動作程式,逐步回報結果

Agent 方向是相對它自己的面向,不是世界方位。

世界(13)

mc_set_blockmc_fillmc_clonemc_test_blockmc_read_blockmc_verify_readingmc_compare_regionsmc_analyze_symmetrymc_query_targetmc_summonmc_world_settings(時間/天氣/遊戲規則/難度)、mc_structure(存讀結構)、mc_ticking_area

mc_query_target 會把 querytarget 回傳的 JSON 字串解析好,這是取得玩家或 Agent 座標的正規做法——建造前先問它。

讀取這一塊有先天限制,講清楚比假裝沒有好。 Education 沒有「讀取任意方塊」的指令,所以:

  • mc_test_block 是是非題:你得先猜一個方塊 ID。

  • mc_read_block 不必猜——它拿空氣當哨兵去問,猜錯時遊戲訊息會把實際方塊講出來。但回傳的是在地化顯示名稱(「泥土」)而不是方塊 ID(dirt),不能餵回 mc_set_block解析不出來時本工具回錯誤,不是回 null 的成功回應——理由見下方。

  • mc_verify_reading 主動驗證上面那條解析路徑還有效。上課前跑一次就知道 mc_read_block 的結果能不能信。

  • mc_compare_regions 用一條 testforblocks 比對整片區域。逐格比對在幾百格以上就會撞到 host 逾時,這個不會。masked 模式忽略來源的空氣,適合檢查「該有的東西在不在」而不管周圍多了什麼——批改學生作品就是這個形狀。

為什麼解析失敗要回錯誤而不是 null

因為這個工具的使用者是 AI,而AI 不會懷疑系統壞掉

一個「成功」的回應配上 block: null,很容易被讀成「讀到了,那裡是空的」。接著 AI 會非常有自信地基於這個錯誤認知繼續做事——例如把學生蓋了一整節課的作品當成空地覆蓋掉,而且事後沒有任何錯誤紀錄可查。人看到 null 會覺得怪並停下來除錯;AI 不會。

錯誤沒辦法被當成資料繼續用,這就是重點。

mc_verify_reading 則是另一半:它不需要事先知道那格是什麼——若該格是空氣就拿基岩去問(空氣不可能是基岩,保證不符)逼出失敗訊息;若該格有東西,第一問就已經給了訊息。兩條路都保證拿得到訊息,最多兩條指令,完全不寫入世界。

這條防線有突變測試守著:故意把解析規則改壞後,探測與解析器共 7 條測試必須轉紅。

要逐格讀整片區域請走行為包與 Script API;本專案刻意不走那條路,因為那會讓學校電腦多一道安裝步驟。

反覆修改同一棟建築

mc_structuresaveMode 就是為這件事設計的:

模式

什麼時候用

生命週期

memory(預設)

AI 改建築時想留退路——存一版,改壞了 load 回來

關掉遊戲就消失,硬碟不留檔

disk

使用者明確說要保留(「幫我記住這棟」)

寫進世界資料夾,關掉遊戲仍在

版本管理就是取名字castle_v1castle_v2。同名會直接覆蓋,改版本前先換名字。

遊戲沒有「列出已存結構」的指令,所以存過什麼只能靠名字記。橋接會記住本次連線存過的名單,問 mc_status 就看得到——但那只涵蓋本行程,重啟就沒了(disk 模式的檔案還在,名字要你自己記)。

對稱性分析——批改作品

mc_analyze_symmetry 檢查一塊區域是否鏡像對稱,不對稱時會指出哪幾塊不對稱,不是只丟一個「否」。

原理:testforblocks 只做平移比對不會鏡像,所以先用 structure save 存下區域,再用 structure load 的 mirror 參數把它鏡像放到暫存區,然後兩區比對。整體通過就直接滿分;不通過才細分成 n³ 格逐格比,分數是相符格子的比例。

這個工具會暫時寫入世界,流程如下,任何一步失敗都不會留下爛攤子:

  1. 存下分析區——失敗就中止(通常是區塊未載入)。

  2. 先備份暫存區——備份失敗就中止,且絕不放置鏡像副本,世界毫髮無傷。

  3. 放鏡像副本、比對。

  4. 不論成敗都還原暫存區並刪掉暫存結構;還原結果如實回報在 scratchRestored,失敗不粉飾。

暫存區不可與分析區重疊,否則鏡像副本會蓋掉原始建築——這個檢查在送出任何指令之前就做。

玩家與回饋(7)

mc_teleportmc_givemc_gamemodemc_effectmc_player_action(kill/clear/xp/ability)、mc_message(say/tell/title/subtitle/actionbar)、mc_feedback(音效/粒子)。

建造(4)

工具

用途

mc_build_preview

只算不做:方塊數、邊界盒、fill 批次數

mc_build_shape

line/box/sphere/ellipsoid/cylinder/cone/pyramid/disk/torus/helix/curve/revolution,多數支援 hollow

mc_blueprint_preview

逐格藍圖的預覽

mc_build_blueprint

任意形狀:給「座標 → 方塊」清單,相同方塊自動合併

事件 — 感知(4)

mc_events_catalogmc_events_subscribemc_events_unsubscribemc_events_poll

事件進環形緩衝,用游標連續讀;dropped > 0 代表輪詢太慢、有事件永遠讀不到了。重新連線後會自動重新訂閱。


4. 為什麼建造不會卡死

天真作法是每個方塊送一次 setblock。一顆半徑 20 的實心球有 33,000 多格,等於三萬多次 WebSocket 往返——實務上等於當機。

BlockHand 的管線是:

形狀參數 → inside() 判定掃描 → 方塊座標集合
        → X 連段合併 → Z 矩形合併 → Y 立方合併(三階段 greedy)
        → 依 Bedrock 單次 /fill 上限 32768 拆批
        → 送出

半徑 8 的實心球從 2,000 多個方塊壓成不到 200 條指令,且合併結果是決定性的——同一組輸入永遠得到同一組批次,所以有測試釘住「合併後覆蓋的方塊集合必須與原始點集合完全相同」,不會多蓋也不會少蓋。

空心形狀一律用「內部判定 + 外殼鄰居測試」實作,而不是每個形狀各寫一套空心數學。新增形狀只要寫 inside(),空心行為自動一致。


5. 安全邊界

不做的事

  • 不連外網:只在 127.0.0.1 開 WebSocket 監聽。

  • MCP runtime 不寫主機檔案:沒有任何 artifact 輸出路徑。只有使用者明確執行 setup:<client>uninstall:<client> 時,該家官方 CLI 才會更新本機 MCP 設定。

  • 一個例外要講清楚mc_structuresaveMode="disk" 會透過遊戲把結構寫成檔案,存進 Minecraft 的世界資料夾。那不是 MCP runtime 在寫檔,但確實會在使用者硬碟上留下東西。所以預設是 memory(暫存,關掉遊戲就消失),只有使用者明確表示要保留時才該用 disk,而且工具回覆一定會講出它寫到哪裡——不會靜悄悄留檔。

  • 不碰祕密:整個專案沒有 token、帳號或憑證。

  • 不主動連線:遊戲不 /connect 進來,所有工具都回可照做的錯誤訊息,不會靜默失敗。

mc_run_command 的閘門

mcp/README.md 架構原則 4 要求拒絕任意執行入口。這裡的判斷是:slash 指令的作用域完全在本機遊戲世界內,不觸及主機檔案系統、行程或網路,所以它不等同任意程式碼執行。真正必須擋的是讓橋接失效的操作,因此政策是結構性的而非猜意圖的關鍵字黑名單:

  1. 只允許單行——換行與 NUL 直接拒絕,不能用 \n 把一條請求拆成兩條指令。

  2. 拒絕 wsserverconnect——那會把遊戲指向別的端點,之後所有工具全部失效。

  3. 其餘指令標記 read-onlyworld-writewide-effect 風險等級,交由 MCP Host 依 annotation 決定是否要人工確認。

所有會被插進指令列的方塊 ID、選擇器、狀態字串都先過白名單正規表達式,防止用空白拼出額外參數。

課堂防護(預設開啟)

上面第 3 點把決定權交給 Host,那在單人開發情境成立,但這個專案的使用現場是教室

  • Host 可能被設成自動核准——老師為了上課順暢很容易這樣做。

  • 學生只要能對那個 AI 說話,就等於能下指令。他不必破解橋接,只要說服模型。

  • 誤用甚至不需要 raw 指令:mc_player_action 本來就接受 @akill 是選項之一。所以只擋 raw 指令是演戲,兩條路都要擋。

規則做成一句話能教給老師的形狀:會作用在「人」身上的動作,必須指名道姓。

路徑

行為

raw 指令

直接拒絕 killkickopdeopclearability

mc_player_action

killclearability 拒絕 @ 開頭的選擇器,必須給玩家名稱

建造與世界設定

完全不受影響(fillsetblockclonestructuretime……)

「殺光全班」因此從一句話變成必須逐一指名,而合法的課堂管理(清掉某個學生的背包)完全不受影響。

要關閉設 MINECRAFT_EDU_CLASSROOM_GUARD=0——錯誤訊息本身就會告訴你這件事,不會讓人以為工具壞了。

商標

Minecraft Usage Guidelines,第三方工具不得看起來像官方產品。產品名 BlockHand 刻意不含 Minecraft 商標;minecraft-edu 只是這個私人工作區內的描述性資料夾名。若日後要對外發布,套件名與任何公開露出都必須重新檢視。


6. 設定

全部有預設值,.env 不是必需品。

變數

預設

說明

MINECRAFT_EDU_WS_HOST

127.0.0.1

監聽位址;預設只綁 loopback

MINECRAFT_EDU_WS_PORT

19131

優先監聽埠;實際值以 mc_status 回報為準

MINECRAFT_EDU_WS_PORT_FALLBACK

1

優先埠被其他 MCP 任務占用時,由作業系統自動配一個空閒埠;設成 0 可要求占埠即失敗

MINECRAFT_EDU_COMMAND_TIMEOUT_MS

10000

單一指令等待遊戲回應的逾時

MINECRAFT_EDU_KEEPALIVE_INTERVAL_MS

30000

閒置時送出保活探測(time query daytime)的間隔。調小可更快發現真的斷線,代價是更常打擾遊戲

MINECRAFT_EDU_EVENT_BUFFER

500

事件環形緩衝筆數

MINECRAFT_EDU_MAX_BUILD_BLOCKS

200000

單次建造方塊數上限,超過即拒絕

MINECRAFT_EDU_CLASSROOM_GUARD

1(開啟)

課堂防護:作用在玩家身上的動作必須指名道姓;raw 指令拒絕 kill/kick/op/deop/clear/ability。設 0 關閉

MINECRAFT_EDU_STEP_DELAY_MS

100

Agent 程式每步預設間隔

MINECRAFT_EDU_DEBUG_FRAMES

未設

設成 1 會把遊戲回的每個原始封包印到 stderr,診斷協定行為用


7. 模組地圖

src/
  domain/                     純資料與純邏輯,不依賴 MCP、ws 或 Node
    contracts.ts              型別、已知事件名、Bedrock fill 上限
    coordinates.ts            絕對/相對/局部座標格式化與邊界檢查
    commands.ts               所有 slash 指令建構器 + 注入白名單
    command-policy.ts         raw 指令的結構性閘門
    build/shapes.ts           十種形狀;inside() + 外殼鄰居測試
    build/fill-planner.ts     三階段 greedy 合併 + 依上限拆批
  ports/minecraft-connection.ts   連線抽象;測試靠它塞假件
  adapters/ws-minecraft-connection.ts  WebSocket 監聽、requestId 對應、事件緩衝、重連重訂閱
  application/
    blockhand-service.ts      Agent 程式展開、querytarget 解析、事件
    build-service.ts          規劃與執行分離(先讀後寫)
  server/
    create-server.ts          server 實例與給 Host 的操作指引
    schemas.ts                共用 zod 片段
    tool-kit.ts               回應塑形與錯誤包裝
    tools/                    session/agent/world/player/build/event
  composition.ts              組裝;可注入假連線
  index.ts                    stdio 入口

領域層完全不知道 WebSocket 的存在,所以整條 MCP 工具管線可以用純記憶體假件測到底——tests/integration/mcp-client.test.ts 的 16 項測試都不需要開遊戲。


8. 已知限制

  • 世界必須開作弊,否則遊戲會拒絕每一條指令。這是 Minecraft 的規則,不是 bug。

  • macOS 已完成真機 live 驗證(Claude Code 路徑):2026-08-25 在 macOS 上經 Claude Code 完成 /connect、大量讀寫(單一工作階段逾 45,000 方塊、含 fillsetblocktestforblockteleport)與斷線重連全流程。尚未驗證的是「從 Finder 啟動 Codex Desktop」這條啟動路徑——GUI 啟動的 PATH 與環境變數繼承方式不同,仍需各自實測。

  • Agent 是 Education Edition 專屬,一般 Bedrock 版沒有這個功能。

  • 事件名稱與 agent 子指令 Mojang 沒有正式文件化,來自公開觀察;遊戲改版可能改變行為。mc_events_subscribe 允許清單外的名稱,但會標記為未驗證。

  • agent setitem 的參數順序未經證實,目前沒有做成專用工具,需要時請走 mc_run_command

  • @s 在 WebSocket 指令下不一定能解析:從橋接送進去的指令沒有實體身分,實測 querytarget @s 會完全沒有回應。mc_query_target 因此預設用 @p(最近的玩家),live 也會依序試 @p@a@e[type=player] 並回報每次結果。

  • 大型建造可能撞到 MCP Host 的請求逾時:建造工具會逐條送出 fill 並等遊戲回應,實測半徑 6 的空心球(126 條)約需 13 秒,但遊戲繁忙時會更久。MCP client 預設逾時多為 60 秒,超過就會在 Host 端被砍斷(工具本身仍在跑)。先用 mc_build_previewfillBatches,數量大時分批建造。

  • 每個 BlockHand 程序仍各自持有一個監聽埠:STDIO client 關閉後,server 會同步關閉 Minecraft WebSocket 並釋放連接埠。AI 工具的桌面版同時載入多個任務,或桌面版/CLI/IDE 並行時,第一份會取得優先埠,其餘會自動取得空閒埠;請一律用目前任務的 mc_status.connectCommand 讓遊戲連到實際要操作的那一份。若需要固定埠,可替各 client 配不同的 MINECRAFT_EDU_WS_PORT,或把 MINECRAFT_EDU_WS_PORT_FALLBACK 設成 0

  • 握手後的第一條指令曾必定逾時,現已修正:四次獨立真機執行都重現——遊戲在伺服器裝好解密器之前就送出一個加密訊框,串流錯位導致下一次請求的回應讀不出來。AES-CFB8 會自我同步,所以只影響第一條。adapter 現在會在握手完成後自動送一條唯讀 time query daytime 把那次損失吸收掉並丟棄結果,呼叫端的第一個動作即可正常。stderr 會記 primed post-handshake stream

  • 事件只在真正發生時觸發BlockPlaced 只在玩家親手放方塊時發出,/setblock/fill 都不算。要收到事件必須先訂閱、再讓事件真的發生。

  • 部分回應的 requestId 對不上請求(觀察到會回全為零的 ID)。adapter 在「只剩一個待決請求」時會把回應歸給它,並在 stderr 記錄這是推斷來的;否則那些請求會一路靜默逾時,呼叫端只看到「沒反應」而不是真正的失敗原因。

  • 一次只維持一條遊戲連線;新連線會取代舊的。

  • 已完成真機驗證的環境:Minecraft Education 1.26.32.0(Win32 桌面版)。若改用 Microsoft Store 的 UWP 版,loopback 會被 Windows 應用程式隔離擋住,需要額外的 CheckNetIsolation LoopbackExempt 豁免。macOS 14+ 的驗收矩陣見 agents/docs/macos-support.md


9. 授權

本專案以 MIT License 釋出。你可以自由使用、修改、散布與再授權,包含商業用途,唯一條件是保留原始的版權聲明與授權條款。

軟體按「現狀」提供,不附任何明示或默示的擔保。

Minecraft、Minecraft Education 為 Mojang Studios 與 Microsoft 的商標;本專案與兩者無隸屬關係,也未獲其背書。

A
license - permissive license
A
quality
B
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.

  • Educational MCP server with 17 math/stats tools, visualizations, and persistent workspace

  • Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gjlmotea/minecraft-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server