Build with AI assistants

Two separate pieces. The MCP server gives an assistant tools that act on your server. Agent Skills teach Claude Code to write MCPyLib scripts.

Before you start

  • A server running the MCPyLib plugin, and its token from /mcpylib token.
  • uv, for the uvx command.

The MCP server reads three environment variables:

VariableValue
MCPYLIB_HOSTAddress of your Minecraft server, localhost if not set
MCPYLIB_PORTThe plugin’s port, 65535 unless you changed it
MCPYLIB_TOKENThe token from /mcpylib token. Required

Connect the MCP server

The server has 86 tools in seven groups (server, blocks, players, world, entities, chat, scoreboard), two prompts (build_structure, survey_area), and resources for server status, player details and a building guide.

Claude Code

Options go before the name (mcpylib); everything after -- starts the server.

claude mcp add \
  --env MCPYLIB_TOKEN=YOUR_TOKEN \
  --transport stdio \
  mcpylib \
  -- uvx --from \
    git+https://github.com/treeleaves30760/MCPyLib-mcp \
    mcpylib-mcp

With only the token set, it connects to localhost:65535. For a remote server, add --env MCPYLIB_HOST=192.168.1.20 before the name, plus --env MCPYLIB_PORT=… if you changed the port. --scope user makes it available in every project. Check with claude mcp list or /mcp.

Claude Desktop

Open Settings > Developer > Edit Config, add the server to claude_desktop_config.json and restart 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. If other servers are listed, add mcpylib to the existing mcpServers object.

Cursor

Use ~/.cursor/mcp.json for all projects or .cursor/mcp.json for one. Cursor fills ${env:NAME} from your environment, so the token stays out of the file.

.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}"
      }
    }
  }
}

Set the three variables in Cursor’s environment, then reload the MCP servers in its settings.

VS Code

Create .vscode/mcp.json in your workspace. VS Code asks for the token on first start and stores it.

.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}"
      }
    }
  }
}

Start the server from the file’s code lens or the MCP view, then use it in Copilot’s agent mode.

Install the Agent Skills

In Claude Code, add the MCPyLib marketplace:

/plugin marketplace add treeleaves30760/MCPyLib-skills

Then install the plugin, which holds all four skills:

/plugin install mcpylib@mcpylib-skills

Claude picks up a skill when a request matches it, or you can call one directly, e.g. /mcpylib:mcpylib-building. To update: /plugin marketplace update mcpylib-skills.

SkillCovers
mcpylibSetup checks, connecting, coordinates and build height, block ids with states and NBT, picking between setblock(), fill(), edit(), clone() and getblocks(), errors and safety. Includes a reference for all 72 methods
mcpylib-buildingSpheres, domes, towers, houses, pixel art and terrain as block arrays, placed with edit() after a dry run, with overwrite protection and an undo file
mcpylib-minigamesPolling loops with a call budget, join and leave detection, scoreboards, teams, boss bars, titles, mobs and cleanup. Includes King of the Hill and a mob arena
mcpylib-mcpSetting up the MCP server for Claude Code, Claude Desktop, Cursor, VS Code and Codex, and when tools beat a script

Or copy a skill’s folder into ~/.claude/skills/ (all projects) or .claude/skills/ (one repository).

Try it

Be specific: give coordinates or player names. For example:

  • Find where Steve is standing and build a 9 × 9 stone platform under him.

  • Read the 20 × 10 × 20 area at 0, 64, 0 and replace every dirt block with moss.

  • Create a kills scoreboard on the sidebar and put Steve and Alex on a red team.

  • Make it night, start a thunderstorm and show a boss bar called Siege to everyone.

Stay safe

  • The token gives full control of the server, including exec(), which runs any command. Only hand it to assistants you trust.
  • Set MCPYLIB_READ_ONLY=true to register only the tools that read, or list tools to hide in MCPYLIB_DENIED_TOOLS, for example run_command.
  • MCPYLIB_MAX_BLOCKS caps how many blocks one tool call may read or change. The default is 100,000.
  • Try new prompts on a test world or a backup first.
  • Keep MCPYLIB_TOKEN out of files you commit.