開始使用

裝好外掛、複製權杖(token),再用 Python 放下第一個方塊。

系統需求

元件需求
Python3.11 或更新版本
Minecraft 伺服器Paper 或 Spigot 26.1 或更新版本。以 26.3 建置,並在 Paper 26.3 與 Spigot 26.3 上實測
Java25 或更新版本

安裝伺服器外掛

從 GitHub Releases 下載 MCPyLib-Plugin-1.2.1.jar,放進伺服器的 plugins 資料夾,重新啟動伺服器。

自己建置需要 Maven 與 JDK 25:

git clone https://github.com/treeleaves30760/MCPyLib.git
cd MCPyLib/ServerPlugin
mvn clean package
# -> target/MCPyLib-Plugin-1.2.1.jar

執行 /plugins,MCPyLib 顯示綠色就是載入成功。

取得權杖

外掛第一次啟動時會產生隨機權杖,存在 plugins/MCPyLib/config.yml。用這個指令查看:

/mcpylib token

在主控台執行,或以管理員身分在遊戲裡執行。權杖等同密碼,拿到的人就能控制你的伺服器。

指令用途
/mcpylib顯示外掛版本與用法
/mcpylib token顯示目前的權杖
/mcpylib token regenerate產生新權杖,舊的會立即失效
/mcpylib status顯示伺服器狀態、連接埠,以及是否啟用權杖驗證
/mcpylib reload重新載入 config.yml

這些指令都需要 mcpylib.admin 權限,管理員預設就有。別名:/mcpy、/mcp。

設定連線

腳本跟伺服器在同一台機器的話,用預設值就好。要改設定,編輯 plugins/MCPyLib/config.yml 後重新啟動。

plugins/MCPyLib/config.yml
server:
  port: 65535                # 外掛監聽的 TCP 連接埠
  host: '0.0.0.0'            # 綁定位址;'127.0.0.1' 只允許本機腳本
  max-connections: 10        # 同時連線數上限,超過時回覆 "Server busy"
  idle-timeout-seconds: 300  # 關閉閒置連線;0 = 永不

security:
  token: ''                  # 第一次啟動時產生
  require-token: true        # 請保持開啟

logging:
  log-connections: true
  log-commands: true

安裝 Python 用戶端

pip install mcpylib

或使用 uv:

uv pip install mcpylib

放下第一個方塊

權杖從環境變數讀,不要寫死在程式碼裡:

first_block.py
import os
from mcpylib import MCPyLib

mc = MCPyLib(
    ip="127.0.0.1",
    port=65535,
    token=os.environ["MCPYLIB_TOKEN"],  # 來自 /mcpylib token
)

mc.setblock(0, 64, 0, "diamond_block")
print(mc.getblock(0, 64, 0))  # minecraft:diamond_block

count = mc.fill(2, 64, 0, 6, 68, 4, "glass")  # 回傳受影響的方塊數
print(count)

設定 MCPYLIB_TOKEN 後執行:

# macOS 與 Linux
MCPYLIB_TOKEN=your-token python first_block.py

# Windows PowerShell
$env:MCPYLIB_TOKEN="your-token"; python first_block.py

用戶端會維持一條連線,斷線自動重連。用完呼叫 mc.close(),或改用 with 區塊:

with MCPyLib(token=os.environ["MCPYLIB_TOKEN"]) as mc:
    mc.say("Hello from Python")
# 離開區塊時連線會關閉

用 edit() 大量建造

setblock() 一個方塊送一個請求,edit() 則把整個三維串列一次送出。方塊一多就用 edit()。

串列索引是 blocks[x][y][z],從你傳入的座標開始。元素可以是方塊名稱、None(保持原樣),或含 block_state 與 nbt 的字典。

xyz
blocks = [
    [["stone", "stone"],      ["glass", None]],     # x = 0
    [["stone", "stone"],      ["glass", "glass"]],  # x = 1
    [["stone", "oak_planks"], [None,    "glass"]],  # x = 2
]  # each x holds y layers; each y layer holds z values
blocks[x][y][z]:最外層是 x(東),再來是 y(上),最內層是 z(南)。None 的位置保持不變。
house.py
house = [[[None] * 10 for _ in range(5)] for _ in range(10)]  # 10 × 5 × 10,全部是 None

for x in range(10):
    for z in range(10):
        house[x][0][z] = "stone"       # 地板
        house[x][4][z] = "oak_planks"  # 屋頂

for y in range(1, 4):
    for i in range(10):
        house[i][y][0] = house[i][y][9] = "cobblestone"  # 南北牆
        house[0][y][i] = house[9][y][i] = "cobblestone"  # 東西牆

house[2][1][2] = {
    "block": "minecraft:chest",
    "block_state": {"facing": "north"},
    "nbt": {"CustomName": '{"text":"Storage"}'},
}

placed = mc.edit(100, 64, 200, house)

getblocks() 回傳同樣是 [x][y][z] 形狀,所以可以讀出一塊區域,改完再寫回去:

area = mc.getblocks(100, 64, 200, 109, 68, 209)

for column in area:          # x
    for row in column:       # y
        for z, block in enumerate(row):
            if block == "minecraft:stone":
                row[z] = "minecraft:deepslate"

mc.edit(100, 64, 200, area)

處理錯誤

每個方法拋出的例外都繼承自 MCPyLibError:

例外發生時機
ConnectionError無法連到伺服器、連線中斷,或指令逾時。逾時後,指令可能仍已在伺服器上執行
AuthenticationError伺服器拒絕權杖
CommandError指令失敗,例如未知的方塊或玩家不在線上
from mcpylib import MCPyLib, AuthenticationError, CommandError, ConnectionError

try:
    mc.teleport("Steve", 0, 100, 0)
except CommandError as e:
    print("指令失敗:", e)
except AuthenticationError:
    print("請用 /mcpylib token 檢查權杖")
except ConnectionError:
    print("伺服器有在執行並載入外掛嗎?")

疑難排解

問題解法
連線被拒(Connection refused)用 /plugins 確認外掛已載入,並確認腳本使用 config.yml 中的連接埠(預設 65535)。
驗證失敗用 /mcpylib token 重新複製權杖,不要帶到空白或換行。不確定時就重新產生。
找不到玩家玩家必須在線上,名稱區分大小寫。
外掛無法載入查看 logs/latest.log,並確認伺服器使用 Java 25 與 Paper 或 Spigot 26.1 以上版本。
連接埠已被占用修改 config.yml 的 server.port,重新啟動,並在腳本中使用相同的連接埠。

下一步