Packwright MCP

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 --run --proposal-sha256 --confirm --workspace /absolute/path/to/datapacks packwright-mcp capture --run --proposal-sha256 --confirm --include-scale-reference-views --workspace /absolute/path/to/datapacks packwright-mcp validate --workspace /absolute/path/to/datapacks packwright-mcp test --workspace /absolute/path/to/datapacks packwright-mcp build --workspace /absolute/path/to/datapacks

Use --json with doctor, setup-version, capture, validate, test, or build for machine-readable output. Run packwright-mcp --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