Packwright MCP

Packwright MCP is a local-first Model Context Protocol server for safely creating, inspecting, validating, testing, and packaging Minecraft Java Edition datapacks and paired resource packs. It gives an MCP client structured tools instead of unrestricted filesystem or shell access.

NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.

Packwright does not contain or redistribute Minecraft code, assets, server/client jars, libraries, natives, generated vanilla data, or decompiled sources. The npm package includes only Packwright's original MIT-licensed capture mod.

Status and compatibility

Packwright supports Minecraft Java Edition 26.2 only: datapack format 107.1 and resource-pack format 88.0. Node.js 20 or newer is required. Default validation, every datapack or paired-project build, vanilla GameTest runs, and official-client visual capture require Java 25 plus the corresponding operator-prepared Minecraft 26.2 cache. Normal authoring, CPU visual drafting/rendering, and an explicitly requested advisory/structural-only validation do not require Java.

The server uses the stable MCP TypeScript SDK v2, targets the MCP 2026-07-28 specification, and relies on SDK protocol negotiation for compatible clients.

The server is local and stdio-only. It does not install packs into a live world, expose an HTTP endpoint, or support Bedrock behavior packs.

What it provides

• Guarded datapack creation and resource editing with atomic writes and SHA-256 preconditions.
• Datapack inspection, resource lookup, and cached Minecraft command/registry search.
• Default vanilla-backed validation of every .mcfunction command with Minecraft 26.2's real dispatcher, registries, and component codecs.
• Always-available structural validation, plus optional diagnostics from an operator-configured external Spyglass process.
• Disposable vanilla pack-loading and GameTest execution after explicit setup.
• Deterministic ZIP builds that fail when structural or vanilla command validation has errors.
• Paired datapack/resource-pack projects with truthful Minecraft native, simulated, replacement, and requires_mod profiles plus a separate compilerSupport implementation status.
• A semantic custom-item model DSL, minecraft:item_model bindings, safe PNG import, profile-specific deterministic CPU previews, immutable repair revisions, and guarded multi-file commit.
• Eight model-specific visual review profiles: held_item, block, placeable, armor, head_wearable, projectile, gui_item, and entity_model, each with deterministic scenes, Packwright-authored reference geometry, advisory measurements, and an immutable render report.
• Explicitly prepared, protocol-v3 framebuffer capture through the actual Minecraft 26.2 client renderer for items plus strict block, headwear, entity, and placeable representations. Required gameplay/world frames are authoritative for the recorded OpenGL environment; injected scale references, debug hitboxes, and matched empty-subject measurement controls are supplemental QA only. Every artifact carries an exact live-client fixture readback and canonical hash. The official client runs in a disposable deterministic studio with only Packwright's capture mod; the CPU renderer remains the fast deterministic first gate.
• Validation of the exact uncommitted proposal over stable datapack/resource-pack snapshots, followed by transactional deterministic ZIPs from the exact committed pack snapshots.
• Read-only MCP resources and workflow prompts for review, scaffolding, and GameTest authoring.

The visual compiler remains intentionally narrower than the Minecraft capability matrix: compilerSupport is full for custom_item, limited for conditional_item_state, and unsupported for every other target. The automatic compiler still emits custom items only. Protocol-v3 capture independently accepts a strict, declarative, hash-bound representation for block, head_wearable, entity_model, or placeable review; this stages existing vanilla identities, replacements, or display simulations but does not claim Packwright compiled a new native block/entity identity. Aggregate client-capture support is full for gui_item, limited for one-handed held_item, block, head_wearable, entity_model, and placeable, and unsupported for armor and projectile. Unsupported strategies are rejected before Minecraft launches. See the paired visual compiler guide and MCP tools, resources, and prompts.

Install and connect

Choose an existing directory that will contain the datapack projects Packwright may access. It must be an absolute path.

Generic MCP client configuration:

{
  "mcpServers": {
    "packwright": {
      "command": "npx",
      "args": [
        "-y",
        "@rithwikbabu/packwright-mcp@0.5.0",
        "serve",
        "--workspace",
        "/absolute/path/to/datapacks"
      ]
    }
  }
}

The workspace can instead be passed through the environment:

{
  "mcpServers": {
    "packwright": {
      "command": "npx",
      "args": ["-y", "@rithwikbabu/packwright-mcp@0.5.0"],
      "env": {
        "PACKWRIGHT_WORKSPACE": "/absolute/path/to/datapacks"
      }
    }
  }
}

Using an exact package version is recommended for predictable automation. The server writes protocol messages only to stdout and sends logs to stderr.

CLI

The installed packwright-mcp binary defaults to serve when no subcommand is supplied:

packwright-mcp serve --workspace /absolute/path/to/datapacks
packwright-mcp doctor --workspace /absolute/path/to/datapacks
packwright-mcp setup-version 26.2 --accept-minecraft-eula --workspace /absolute/path/to/datapacks
packwright-mcp setup-version 26.2 --accept-minecraft-eula --client-assets --workspace /absolute/path/to/datapacks
packwright-mcp setup-version 26.2 --accept-minecraft-eula --client-capture --workspace /absolute/path/to/datapacks
packwright-mcp capture <project-id> --run <sha256> --proposal-sha256 <sha256> --confirm --workspace /absolute/path/to/datapacks
packwright-mcp capture <project-id> --run <sha256> --proposal-sha256 <sha256> --confirm --include-scale-reference-views --workspace /absolute/path/to/datapacks
packwright-mcp validate <pack> --workspace /absolute/path/to/datapacks
packwright-mcp test <pack> --workspace /absolute/path/to/datapacks
packwright-mcp build <pack> --workspace /absolute/path/to/datapacks

Use --json with doctor, setup-version, capture, validate, test, or build for machine-readable output. Run packwright-mcp <command> --help for command-specific options. See the CLI reference and Configuration for all flags, precedence, environment variables, and exit behavior.

Vanilla setup and testing

setup-version is an explicit operator action. It records acceptance of the Minecraft EULA, obtains the official 26.2 server jar from Mojang, verifies the SHA-1 declared by Mojang's version manifest, and prepares local validation data. The MCP server never downloads the jar or accepts terms on a model's behalf.

packwright-mcp setup-version 26.2 \
  --accept-minecraft-eula \
  --workspace /absolute/path/to/datapacks

Add --client-assets only to prepare the official client jar and asset-index readiness metadata used by asset-aware tooling. Add --client-capture to prepare the complete platform-specific launcher runtime, every indexed asset object, required libraries and natives, and pinned Fabric Loader 0.19.3; it implies the client-assets step. Every downloaded artifact is allow-listed and checked against the Mojang or Packwright-pinned digest. Minecraft client artifacts remain only in the local cache and are never copied into the workspace, npm package, or release artifacts. Semantic compilation still requires custom external textures/models to exist at their normal paths in the paired resource pack; it does not copy them from the client cache.