輸入 Python,輸出方塊。

一個 Paper/Spigot 外掛加上一個 Python 用戶端。腳本可以放方塊、一次改寫整個區域、移動玩家、下伺服器指令。

pip install mcpylib
伺服器
Paper 或 Spigot 26.1+
Java
25
Python
3.11+
import mathfrom mcpylib import MCPyLibmc = MCPyLib(token="YOUR_TOKEN")size, peak = 20, 6def height(x, z):    d = math.hypot(x - size / 2, z - size / 2) / (size / 2)    return int(peak * (1 - d * d) + math.sin(x / 2) * math.cos(z / 3))island = [[["grass_block" if y == height(x, z) else "dirt"            if y < height(x, z) else None            for z in range(size)] for y in range(peak + 2)]          for x in range(size)]mc.fill(-2, 63, -2, size + 1, 63, size + 1, "water")# 回傳 576mc.edit(0, 64, 0, island)# 回傳 1125c, t = size // 2, size // 3mc.placeFeature("minecraft:oak", t, 65 + height(t, c), c)# 回傳 Truemc.setblock(c, 65 + height(c, c), c, "sea_lantern")# 回傳 1

4 次呼叫,共 1,761 個方塊

這是瀏覽器裡的模擬,拿去對伺服器執行就會真的蓋出來。 拖曳或用方向鍵改標亮的數字。

一次方法呼叫,一行 JSON

每個方法透過 TCP 送出一個 JSON 請求,收回一行 JSON。連線在呼叫之間保持開啟,斷線會自動重連。

  1. 你的腳本

    mc.setblock(
        100, 64, 200,
        "stone")
  2. 送往連接埠 65535 的請求

    {"token": "…",
     "action": "setblock",
     "params": {
      "x": 100, "y": 64,
      "z": 200,
      "block": "stone"}}
  3. Paper/Spigot 上的外掛

    驗證權杖,然後在主執行緒執行指令。

  4. 回應

    {"success": true,
     "data": 1,
     "error": null}
  5. 世界中

    100, 64, 200

出錯時會拋出 ConnectionError、AuthenticationError 或 CommandError,都繼承自 MCPyLibError。

約 60 毫秒放好 16,384 個方塊

Paper 26.3、外掛 1.2.0,一次 edit() 呼叫。外掛把一般方塊直接寫進區塊區段,不觸發逐方塊事件,也不更新光照。

下面的測試兩邊都只放一種方塊。edit() 另外還能每格放不同的方塊。

每秒放置方塊數,依區域大小
顯示數據表
區域方塊數fill()edit()
小 10 × 10 × 101,000 個方塊1,0000.0525 秒19,060/s0.0473 秒21,133/s
中 20 × 20 × 104,000 個方塊4,0000.0548 秒72,945/s0.0484 秒82,593/s
大 30 × 30 × 109,000 個方塊9,0000.0608 秒147,999/s0.0530 秒169,737/s
特大 50 × 50 × 1025,000 個方塊25,0000.0886 秒282,222/s0.1031 秒242,384/s
巨大 100 × 100 × 550,000 個方塊50,0000.7618 秒65,630/s0.4564 秒109,551/s

從 Python 量的單次呼叫實際耗時,含網路往返,取自 fill_vs_edit.py 的一次執行。數字會隨硬體與伺服器負載變動。

一次 edit() 呼叫送出了什麼

以一面 1 × 3 × 3、中間有玻璃窗的牆為例:

wall = [[["stone", "stone", "stone"],
         ["stone", "glass", "stone"],
         ["stone", "stone", "stone"]]]

mc.edit(0, 64, 0, wall)  # returns 9
  1. 攤平依 x、y、z 順序讀取 blocks[x][y][z]
  2. 調色盤每種不同的方塊對應一個索引["stone", "glass"]0 0 0 0 1 0 0 0 0
  3. 連續長度編碼連續相同的索引壓成「數量, 索引」4,01,14,0
  4. 壓縮zlib 壓縮後再轉成 base64 放進 JSON 請求"eJwz0THQMQRCEx0DAAw3Agc="
  5. 寫入送出一個 bulkEdit 請求,外掛每個區塊區段只寫一次"action": "bulkEdit""sizeX": 1"sizeY": 3"sizeZ": 3

搭配 AI 助理

MCP 伺服器讓助理能直接操作你的伺服器;Agent Skills 教 Claude Code 寫 MCPyLib 腳本。

MCP 伺服器

用 uvx 在本機執行,主機、連接埠和權杖都跟腳本一樣。

claude mcp add \
  --env MCPYLIB_TOKEN=YOUR_TOKEN \
  --transport stdio \
  mcpylib \
  -- uvx --from \
    git+https://github.com/treeleaves30760/MCPyLib-mcp \
    mcpylib-mcp
工具
86 個,分七組
提示
build_structure 與 survey_area
安全
唯讀模式、工具允許與封鎖清單、單次呼叫方塊上限
用戶端
Claude Code、Claude Desktop、Cursor、VS Code,或任何 MCP 用戶端

Agent Skills

一個 Claude Code 外掛,內含四個技能。

/plugin marketplace add treeleaves30760/MCPyLib-skills
/plugin install mcpylib@mcpylib-skills
mcpylib
環境檢查、連線、選對放置方塊的方法、錯誤處理
mcpylib-building
形狀、建築、像素畫與地形,以 edit() 放置並可復原
mcpylib-minigames
遊戲迴圈、計分板、隊伍、Boss 血條、生物與收尾清理
mcpylib-mcp
設定 MCP 伺服器,以及何時用工具比寫腳本好
設定你的 AI 助理

用 MCPyLib 做的專案

新月與橘子組成的標誌,以階梯模式加抖動重建成 Minecraft 地圖畫。標記處的月亮邊緣放大四倍:抖動讓地圖顏色逐像素交錯。

Map Art 地圖畫

把圖片轉成地圖畫。階梯模式調整方塊高低,可用的地圖顏色從 60 種變成 180 種。

階梯+抖動:PSNR 28.85 dB,使用 99 種顏色

生成山脈的陰影地形圖,有積雪的山脊、森林與河流。

Terrain 地形生成

以水力侵蝕、河流與生態域生成山脈,再用 edit() 逐區塊放進世界。

1024 × 1024 方塊,高度 Y 34 到 270

看更多作品

快速開始

  1. 安裝外掛

    把 MCPyLib-Plugin-1.2.1.jar 放進伺服器的 plugins 資料夾,重新啟動。需要 Paper 或 Spigot 26.1+、Java 25。

  2. 複製權杖

    在伺服器主控台,或以管理員身分在遊戲裡執行:

    /mcpylib token
  3. 安裝用戶端並連線

    pip install mcpylib

    接著用你的權杖執行腳本:

    first_block.py
    from mcpylib import MCPyLib
    
    mc = MCPyLib(token="YOUR_TOKEN")
    x, y, z = mc.getPos("Steve")
    mc.setblock(x, y - 1, z, "gold_block")
閱讀完整教學

常見問題

MCPyLib 是 Minecraft 官方產品嗎?

不是。這是獨立專案,未經 Mojang 或 Microsoft 認可,也和他們沒有關係。

支援哪些伺服器?

Paper 與 Spigot 26.1 以上,Java 25。在 Paper 26.3 和 Spigot 26.3 上測過。1.21.x 請繼續用 1.1.x 版外掛。原版、Fabric、Forge 伺服器不能載入 Bukkit 外掛。

可以免費使用嗎?

非商業用途免費:個人專案、學習、不收學費的研究、開源專案、非營利組織。MCPyLib 是原始碼公開(source-available),不是開源授權。商業用途(含付費課程與公司內部使用)需要商業授權,請寄信到 treeleaves30760@gmail.com。

開放連接埠安全嗎?

請求都要帶權杖,但連線沒有加密。腳本在本機的話,讓外掛只綁 127.0.0.1;不然就只開放給信任的位址。權杖外洩時執行 /mcpylib token regenerate。

速度有多快?

在 Paper 26.3 上,一次 16,384 個方塊的 edit() 約 60 毫秒,含網路往返。

沒有包裝的指令怎麼辦?

用 mc.exec("..."),開頭的斜線可加可不加。

支援哪些 Python 版本?

Python 3.11 以上。用 pip install mcpylib 或 uv pip install mcpylib 安裝。

AI 助理能使用嗎?

可以,透過 MCP 伺服器或 Agent Skills。詳見AI 整合。