和 AI 助理一起建造

分成兩塊,可以只用其中一個。MCP 伺服器讓助理能直接操作你的伺服器;Agent Skills 教 Claude Code 寫 MCPyLib 腳本。

開始之前

  • 一台執行 MCPyLib 外掛的伺服器,以及用 /mcpylib token 取得的權杖。
  • 裝好 uv,會用到它的 uvx 指令。

MCP 伺服器讀取這三個環境變數:

變數值
MCPYLIB_HOSTMinecraft 伺服器的位址,未設定時為 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。

claude_desktop_config.json
{
  "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},權杖不用寫進檔案。

.cursor/mcp.json
{
  "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 會詢問權杖並記住。

.vscode/mcp.json
{
  "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 寫進會提交的檔案。