開始使用
裝好外掛、複製權杖(token),再用 Python 放下第一個方塊。
系統需求
| 元件 | 需求 |
|---|---|
| Python | 3.11 或更新版本 |
| Minecraft 伺服器 | Paper 或 Spigot 26.1 或更新版本。以 26.3 建置,並在 Paper 26.3 與 Spigot 26.3 上實測 |
| Java | 25 或更新版本 |
安裝伺服器外掛
從 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 後重新啟動。
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放下第一個方塊
權杖從環境變數讀,不要寫死在程式碼裡:
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 的字典。
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 valueshouse = [[[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,重新啟動,並在腳本中使用相同的連接埠。 |
下一步
- 在 API 參考瀏覽所有方法。
- 用 MCP 伺服器與 Agent Skills 接上 AI 助理。
- 更多範例在 GitHub:小木屋、迷宮產生器、沙子小遊戲、實體控制,以及
fill()對edit()的效能比較。