和 AI 助理一起建造
分成兩塊,可以只用其中一個。MCP 伺服器讓助理能直接操作你的伺服器;Agent Skills 教 Claude Code 寫 MCPyLib 腳本。
開始之前
- 一台執行 MCPyLib 外掛的伺服器,以及用
/mcpylib token取得的權杖。 - 裝好 uv,會用到它的
uvx指令。
MCP 伺服器讀取這三個環境變數:
| 變數 | 值 |
|---|---|
MCPYLIB_HOST | Minecraft 伺服器的位址,未設定時為 localhost |
MCPYLIB_PORT | 外掛的連接埠,沒改過就是 65535 |
MCPYLIB_TOKEN | 用 /mcpylib token 取得的權杖,必填 |
連接 MCP 伺服器
伺服器有 86 個工具,分成七組(server、blocks、players、world、entities、chat、scoreboard),兩個提示(build_structure、survey_area),以及伺服器狀態、玩家資訊和建造指南等資源。
Claude Code
選項放在名稱(mcpylib)前面;-- 之後是啟動伺服器的指令。
claude mcp add \
--env MCPYLIB_TOKEN=YOUR_TOKEN \
--transport stdio \
mcpylib \
-- uvx --from \
git+https://github.com/treeleaves30760/MCPyLib-mcp \
mcpylib-mcp只設權杖時會連到 localhost:65535。伺服器在別台機器的話,在名稱前加 --env MCPYLIB_HOST=192.168.1.20;改過連接埠再加 --env MCPYLIB_PORT=…。加 --scope user 就能在所有專案使用。用 claude mcp list 或 /mcp 檢查。
Claude Desktop
打開「設定」→「開發者」→「編輯設定」,把伺服器加進 claude_desktop_config.json,再重開 Claude Desktop。
{
"mcpServers": {
"mcpylib": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/treeleaves30760/MCPyLib-mcp",
"mcpylib-mcp"
],
"env": {
"MCPYLIB_HOST": "127.0.0.1",
"MCPYLIB_PORT": "65535",
"MCPYLIB_TOKEN": "YOUR_TOKEN"
}
}
}
}macOS:~/Library/Application Support/Claude/claude_desktop_config.json。Windows:%APPDATA%\Claude\claude_desktop_config.json。檔案裡已經有其他伺服器的話,把 mcpylib 加進現有的 mcpServers 物件。
Cursor
所有專案共用就寫在 ~/.cursor/mcp.json,單一專案則用 .cursor/mcp.json。Cursor 會從環境變數填入 ${env:NAME},權杖不用寫進檔案。
{
"mcpServers": {
"mcpylib": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/treeleaves30760/MCPyLib-mcp",
"mcpylib-mcp"
],
"env": {
"MCPYLIB_HOST": "${env:MCPYLIB_HOST}",
"MCPYLIB_PORT": "${env:MCPYLIB_PORT}",
"MCPYLIB_TOKEN": "${env:MCPYLIB_TOKEN}"
}
}
}
}在 Cursor 的執行環境設好這三個變數,再到設定裡重新載入 MCP 伺服器。
VS Code
在工作區建立 .vscode/mcp.json。伺服器第一次啟動時,VS Code 會詢問權杖並記住。
{
"inputs": [
{
"type": "promptString",
"id": "mcpylib-token",
"description": "MCPyLib token",
"password": true
}
],
"servers": {
"mcpylib": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/treeleaves30760/MCPyLib-mcp",
"mcpylib-mcp"
],
"env": {
"MCPYLIB_HOST": "127.0.0.1",
"MCPYLIB_PORT": "65535",
"MCPYLIB_TOKEN": "${input:mcpylib-token}"
}
}
}
}從檔案上的 code lens 或 MCP 檢視啟動伺服器,然後在 Copilot 的代理模式裡使用。
安裝 Agent Skills
在 Claude Code 加入 MCPyLib marketplace:
/plugin marketplace add treeleaves30760/MCPyLib-skills再安裝外掛,四個技能都在裡面:
/plugin install mcpylib@mcpylib-skills需求對得上時,Claude 會自己載入技能;也可以直接呼叫,例如 /mcpylib:mcpylib-building。更新:/plugin marketplace update mcpylib-skills。
| 技能 | 內容 |
|---|---|
mcpylib | 環境檢查、連線、座標與建築高度、含狀態與 NBT 的方塊 ID、setblock()/fill()/edit()/clone()/getblocks() 怎麼選、錯誤處理與安全守則,附全部 72 個方法的參考 |
mcpylib-building | 球體、圓頂、塔、房屋、像素畫與地形轉成方塊陣列,先試跑再用 edit() 放置,有覆寫保護和復原檔 |
mcpylib-minigames | 限制呼叫次數的輪詢迴圈、玩家進出偵測、計分板、隊伍、Boss 血條、標題、生物與收尾清理。附「山丘之王」和怪物競技場 |
mcpylib-mcp | 在 Claude Code、Claude Desktop、Cursor、VS Code、Codex 設定 MCP 伺服器,以及什麼時候用工具比寫腳本好 |
也可以把技能資料夾直接複製到 ~/.claude/skills/(所有專案)或儲存庫裡的 .claude/skills/。
試試看
需求講具體一點,附上座標或玩家名稱。例如:
找出 Steve 站的位置,在他腳下蓋一個 9 × 9 的石頭平台。
讀取 0, 64, 0 開始 20 × 10 × 20 的區域,把所有泥土換成苔蘚。
在側邊欄建立擊殺計分板,並把 Steve 和 Alex 編進紅隊。
把時間改成晚上、開始雷雨,並對所有人顯示名為 Siege 的 Boss 血條。
安全須知
- 權杖等於伺服器的完整控制權,包括能執行任何指令的
exec()。只交給你信任的助理。 - 設
MCPYLIB_READ_ONLY=true只開放讀取類工具,或在MCPYLIB_DENIED_TOOLS列出要隱藏的工具,例如run_command。 MCPYLIB_MAX_BLOCKS限制單次工具呼叫能讀取或修改的方塊數,預設 100,000。- 新提示先拿測試世界或備份試。
- 不要把
MCPYLIB_TOKEN寫進會提交的檔案。