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.

visual_capture is a separate, explicitly confirmed MCP operation. It requires Java 25, the completed --client-capture setup, and an interactive macOS graphical session capable of creating a real OpenGL window. Packwright creates hash-bound staging archives for the exact datapack/resource-pack proposal and launches the official client in offline developer mode with multiplayer and chat disabled. The resource-pack archive is staged as resourcepacks/packwright-proposal.zip and remains active during capture. The datapack archive is staged only as non-loadable provenance at packwright/provenance/datapack-proposal.zip; it is never installed in the disposable world, enabled, or selected. The world's loadable datapacks/ directory must remain empty, the integrated server must select exactly vanilla, and its available pack IDs must match Packwright's fixed Minecraft 26.2 built-in allow-list; any selected file/ pack, unexpected available pack, or filesystem entry aborts capture. The client runs only Packwright's bundled capture mod in a fresh disposable void-style studio, captures through Minecraft's screenshot API, and deletes the disposable game directory afterward. The report attests both activation modes, archive hashes, and selected pack IDs in addition to binding the representation, proposal and full pack snapshots, client/mod, OS/GPU/driver/OpenGL backend, resolution, GUI scale, FOV, render settings, camera, biome, time, weather, observed subject light plus deterministic light-source placement, tick/animation state, settling interval, source framebuffer hashes, and an exact live-client observed-fixture readback/hash for every view. Protocol v3 also requires a hash-bound ordinary-block floor ruler: black and white concrete occupy two fixed adjacent blocks, the capture mod places them through the integrated server, and every completed view records a live client readback plus canonical SHA-256. Because the ruler is ordinary studio geometry, it may provide authoritative world-scale context; the separate injected mannequin remains supplemental. An equippable_head plan always includes authoritative armor-stand front and side scenes. The studio records Minecraft's custom graphics preset because its fixed cloud, particle, shadow, render-distance, and simulation-distance overrides intentionally differ from an unmodified preset. Protocol v3 accepts static display nodes only, cannot claim a resettable block-atlas animation phase, and requires simulated entity rigs to provide separate exact idle, walk, and attack states.

By default, every first-person gameplay scene is first_person_vanilla: exact stock composition with no Packwright-injected arm. includeScaleReferenceViews adds paired first_person_scale_reference frames; includeDebugHitboxViews adds supported entity/placeable debug_hitbox_reference frames. Those opt-ins, bare-head comparisons, matched empty-subject measurement_control frames, and any same-frame injected comparison_reference or non-ordinary world_scale_reference aid carry augmented_qa_reference, appear only in the separate supplemental QA sheet, never enter pack output, and never satisfy authority. The entity profile's entity_player_scale mannequin is specifically a supplemental world_scale_reference, never authoritative gameplay/world evidence. Ordinary world geometry—and an armor stand when it is the actual declared headwear subject—can remain exact authoritative Minecraft frames. Non-skipped client measurements are derived from the bound framebuffer pixels; unavailable geometric checks are explicitly skipped with a reason rather than copied from CPU advisory measurements. A measurement that consumes a supplemental control remains advisory, even when its primary scene is required. Packwright never accepts account credentials, a user save, arbitrary commands/functions, executable content, or unapproved paths, and never falls back to CPU output.

For every profile with full or limited client support, production visual_validate requires current official-client evidence by default. visual_commit requires both the exact verified capture-report SHA-256 and proposalBindingStatus: "implemented". Protocol-v3 block, headwear, entity, and placeable results are currently capture_only: they provide exact representation QA but cannot authorize the current item-compiler proposal until that proposal implements the captured representation. A two-handed held item or unsupported representation is rejected rather than receiving incomplete client authority. Pass requireClientCapture: false only for explicitly advisory/fast validation; it does not make a supported-profile proposal committable. Profiles whose client implementation is truthfully unsupported keep their CPU-only path.

Required stock views, including first_person_vanilla, equipped player/armor-stand headwear subjects, and ordinary studio/world frames, have authoritative_environment_capture authority: they prove what the pinned client rendered for the exact recorded representation and environment. authorityScope: "required_views_only" explicitly excludes every bare-head or injected scale/comparison, debug-hitbox, matched measurement-control, and world_scale_reference aid—including the entity_player_scale mannequin; no supplemental frame or skipped supplemental measurement can replace a missing or failed required view. Every pixel measurement binds an explicit requiredForReadiness value. A failed or skipped critical measurement makes capture readiness false and blocks commit; critical warnings and best-effort skips remain visible without being greenwashed as measured passes. Supplemental-control/debug measurements are never critical. Hardware and drivers can legitimately change pixels, so screenshots are not promised byte-identical across GPUs or operating systems. A passed capture means the required evidence completed, verified, and has no failed or unavailable critical measurement—not that its appearance was aesthetically approved.

After setup, validate uses the pinned vanilla runtime by default to parse each logical .mcfunction command against Minecraft 26.2's real command dispatcher, loaded datapack registries, and component codecs. This catches invalid command, selector, item/component, particle, attribute, entity, and text-component syntax before packaging. validate --no-vanilla is the explicit structural-only escape hatch; builds never provide that bypass.

Both command validation and authoritative tests run Java 25 in newly created disposable state. Command validation substitutes inert placeholders for the pack's functions and validates unreferenced command probes, so it does not execute user functions. GameTests receive a freshly allocated universe; a user world path is never accepted. See Validation and vanilla testing.

Function-type GameTests resolve Minecraft's internal test_function registry; a datapack .mcfunction does not register a Test Function. Use minecraft:always_pass only for pack-load/runner smoke coverage, or an existing block-based test structure for behavior-focused tests.

Spyglass is deliberately not installed as a runtime dependency. The adapter is compatibility-pinned to Spyglass 0.4.65 and verifies the configured executable's --version output before use. An operator who has independently installed and reviewed a safe build may opt in with PACKWRIGHT_SPYGLASS_COMMAND; Packwright never downloads or enables it automatically.

Safety model

Packwright resolves every requested path beneath the configured workspace, rejects traversal and symlink escapes, limits scans and payloads, and never recursively deletes directories. Existing files can be replaced or deleted only with explicit intent and the current SHA-256. Raw authoring is limited to supported datapack text formats; binary NBT and pack.png may be inspected and packaged but not authored. Visual textures use a dedicated bounded PNG decoder, and accepted cross-pack proposals commit through a journaled transaction with all destination hashes checked first.

Read Security model before granting the server access to valuable projects. Consider source control and PACKWRIGHT_READ_ONLY=true for review-only sessions.

For common startup, cache, Java, validation, and build failures, see Troubleshooting. Maintainers and contributors can find the component boundaries in Architecture.

Development

npm ci
npm run lint
npm run format:check
npm run typecheck
npm test
npm run build
npm pack --dry-run

Minecraft integration tests are intentionally separate because they download Mojang artifacts and require Java 25 plus explicit EULA acceptance. The official-client capture release gate additionally requires a protected, interactive macOS machine; ordinary CI does not download or launch the client. Contribution setup and test expectations are in CONTRIBUTING.md.

License and trademarks

Packwright MCP is available under the MIT License. External software and service terms are summarized in THIRD_PARTY_NOTICES.md.

Minecraft is a trademark of Microsoft Corporation. This project follows the Minecraft Usage Guidelines and uses no Mojang or Microsoft artwork.