Texel Mcp

Texel

Texel is a format and a toolchain for making Minecraft textures as code. A texture is a JSON spec: a palette and an ordered list of drawing operations addressed to named parts and faces of the model (head.front, rightArm.sides@overlay). A compiler turns the spec into the PNG the game reads, the same bytes every time, and a review returns what is wrong with it as JSON paths, fix hints, an art score and pixel-art advice. The tools are built for AI agents: an MCP server, a command-line tool and an Agent Skill, also packaged as a Claude Code plugin.

It covers player skins (classic and slim) and, through layouts, 25 other textures: mobs such as zombies, skeletons, creepers, pigs, wolves and iron golems, armor layers, capes with elytra, and 16 × 16 items and blocks, all in the Java Edition 1.21 texture layouts.

Texel is open source (MIT) and in development, at version 0.8.0. The format is versioned (version: 1) but may still change between minor releases. Treat everything as a beta. The site texel.dev.br is built on this toolchain.

[Review sheet of the wizard example: front, back and both sides, then the texture]

The image above is the review sheet the tools return for this spec. It is the wizard example without its $schema, description, author and tags fields and the layers' note comments, which do not change the pixels (both compile to the same PNG):

{  "version": 1,  "name": "Star Wizard",  "model": "classic",  "palette": {    "skin": "#e0ac7e", "robe": "#2f4fb0", "gold": "#e8c34a", "beard": "#dcdcdc",    "eyes": "#3a6fd9", "boots": "#4a3324", "star": "#fff1a8"  },  "layers": [    { "op": "material", "target": "all", "color": "skin", "kind": "skin" },    { "op": "material", "target": "body+arms", "color": "robe", "kind": "fabric" },    { "op": "material", "target": "legs", "color": "robe~-1", "kind": "fabric" },    { "op": "material", "target": "arms", "region": "hands", "color": "skin", "kind": "skin" },    { "op": "rect", "target": "arms.sides", "region": "cuffs", "color": "gold" },    { "op": "material", "target": "legs", "region": "boots", "color": "boots", "kind": "leather" },    { "op": "face", "id": "face", "skin": "skin", "eyes": "eyes", "brows": "beard", "beard": "full", "beardColor": "beard", "mouth": "smile" },    { "op": "hair", "id": "hair", "color": "beard", "style": "long", "fringe": "parted" },    { "op": "lighting" },    { "op": "rect", "target": "body.sides", "region": "belt", "color": "gold" },    { "op": "points", "target": "body.front", "points": [[3, 8], [4, 8]], "color": "gold~-2" },    { "op": "points", "target": "body.front+back", "points": [[1, 2], [6, 4], [2, 6], [5, 10]], "color": "star" },    { "op": "points", "target": "legs.front", "points": [[1, 1], [2, 4]], "color": "star" },    { "op": "material", "id": "hood", "target": "body.back@overlay", "y": 0, "h": 3, "color": "robe~-1", "kind": "fabric" },    { "op": "rect", "target": "body.front@overlay", "region": "collar", "color": "gold~-1" },    { "op": "rect", "target": "arms.sides@overlay", "region": "cuffs", "color": "gold~1" }  ]}

The 64 × 64 texture it compiles to is docs/images/wizard.png.

Installing

The MCP server and the CLI need Node 20 or later.

Claude Code plugin. This repository is a plugin marketplace. The plugin starts the MCP server from a single bundled file (no npm install) and adds the minecraft-skin-design skill. Files are written to the project directory.

/plugin marketplace add Brunovncs/texel-mcp/plugin install texel@texel

Or use this prompt. Paste it into the agent you want to use Texel with (Claude Code, Codex, Cursor, Claude Desktop or any other client with MCP support) and it installs the MCP server for you:

Install the Texel MCP server for me (https://github.com/Brunovncs/texel-mcp).
1. Check that Node.js 20 or later is installed (`node --version`). If it is not, stop and tell me.2. Create the folder ~/.texel (%USERPROFILE%\.texel on Windows) and download the single-file   server into it:   https://raw.githubusercontent.com/Brunovncs/texel-mcp/main/plugin/server/texel-mcp.mjs3. Check that it runs: `node <path to texel-mcp.mjs> --version` must print a version number.4. Ask me which folder the skins should be saved in. If I don't care, skip the --workspace part   below; files then go to the directory the client starts the server in.5. Register it as an MCP server named "texel" in the client you are running in, using absolute   paths:   - Claude Code: claude mcp add --scope user texel -- node <path to texel-mcp.mjs> --workspace <folder>   - Any other client: add this to its MCP configuration, keeping the servers already there:     {"mcpServers": {"texel": {"command": "node",       "args": ["<path to texel-mcp.mjs>", "--workspace", "<folder>"]}}}6. Tell me what you changed and whether I need to restart the client. Once the tools are   available, call texel_get_example and then texel_render on that example to confirm they work.

Any MCP client. The package is texel-mcp on npm. This configuration works in Claude Desktop, Cursor, VS Code and other clients that read the usual mcpServers format:

{  "mcpServers": {    "texel": {      "command": "npx",      "args": ["-y", "texel-mcp", "--workspace", "/absolute/path/skins"]    }  }}

In Claude Code the same is claude mcp add texel -- npx -y texel-mcp. To run a local build instead (see Building and testing), point the client at the file: "command": "node", "args": ["/absolute/path/texel-mcp/dist/texel-mcp.mjs", "--workspace", "/absolute/path/skins"]. plugin/server/texel-mcp.mjs is the same server with its dependencies bundled, and runs from anywhere with plain node.

CLI. npx -y -p texel-mcp texel-cli build skin.json -o skin.png --sheet sheet.png, or node dist/texel.mjs ... from a build. It has no dependencies. --help lists the commands: build, review, patch, sheet, palette, family, import, diff, share, pull, live, format, layouts and init.

All writes go to one workspace directory: --workspace, $TEXEL_WORKSPACE, or the directory the server was started in. Paths that resolve outside it are refused. docs/install.md has the details, including installing the skill by hand.

The spec

A spec has a palette (names for colors, with derived tones such as robe~-1, a step darker and cooler), an optional legend (one character per color, for pixel rows) and layers, which run in order. Each layer is one of 17 operations. Twelve are plain drawing (fill, rect, clear, pixels, points, line, gradient, pattern, noise, shade, copy, mirror), one fixes symmetry (symmetrize) and four are higher level: material (fabric, leather, metal, fur, knit and other surfaces), face, hair and lighting.

A layer's target is a selector: parts, faces and a layer, as in head.front, legs.sides, body.front+back@overlay or arms.top@both. Coordinates are local to each face: (0, 0) is the top-left pixel of the face as seen from outside the model, and drawing is clipped to the face. A selector that matches several faces runs the operation once per face, so { "op": "rect", "target": "legs.sides", "y": -2, "color": "boots" } paints the bottom two rows all the way around both legs. Named regions (belt, cuffs, boots, hands, collar) stand in for row numbers.

Changes are made with patches by layer id ({ "patch": [{ "do": "update", "id": "hair", "set": { "style": "ponytail" } }] }), so a fix round touches only the layers it names. A family document expands one base spec into variants or a matrix of axes (teams, ranks, factions) by swapping palettes, turning layers on and off and appending layers. An existing PNG can be imported into an editable spec, one layer per painted face.

The full reference is docs/spec.md, with a JSON Schema in schema/skinspec.v1.json. docs/protocol.md describes the loop an agent is expected to follow (brief, draft, render, review, patch, ship), and docs/art-guide.md what makes a skin read well at 64 × 64. The same pages are available to the agent through texel_read_docs and the texel://docs/{page} resources, and the 13 examples in examples/ through texel_get_example.

What the review returns

Every render comes with a review. With a typo in a palette name and in a face name, the relevant part of the answer is:

{  "ok": false,  "score": 38,  "issues": [    { "level": "error", "code": "bad-color", "path": "$.layers[1].color",      "message": "unknown color or palette key \"clth\"", "hint": "did you mean \"cloth\"?" },    { "level": "error", "code": "bad-selector", "path": "$.layers[2].target",      "message": "unknown face \"frnt\"", "hint": "did you mean \"front\"?" },    { "level": "warning", "code": "blank-face", "path": "head.front",      "message": "the face (head.front) uses fewer than 3 colors and will read as blank",      "hint": "draw eyes, brows and a mouth with a \"pixels\" op on head.front" }  ]}

Errors and warnings point at the JSON path or the face that caused them, and most carry a hint that names the fix. The score (0 to 100) only measures technical hygiene: errors, holes in the base layer, blank faces, flat surfaces, too few colors. The art part of the review has its own score from seven measured checks: R2 to R7 (face readability, lightness contrast between parts, light from above, surface texture, a designed back, use of the overlay for depth) and a color count, each with a note on what was measured and a hint. art.advice names classic pixel-art mistakes found in the texture (pillow shading, shadows that only get darker, static-like noise, a band that stops at a cube corner) with the faces where they show; it never changes a score. A next list orders what to fix first.

Whether the texture matches the brief (R1) is never measured. The MCP tools return a review sheet image (front, back, both sides and the texture, as above) so an agent with vision can judge that itself, and a text render for models without vision. In clients that support MCP Apps, texel_render also opens an interactive 3D preview.

Tools

The MCP server has 14 tools, resources for the docs, examples and schemas, the ui://texel/viewer MCP App and 4 prompts (design_skin, continue_skin, design_family, critique_skin).

How it works

The hard part of drawing a Minecraft texture is not the drawing but the map. A skin's right arm is six rectangles scattered over a 64 × 64 atlas, some mirrored, the overlay layer is a second set of rectangles elsewhere, a pig's body lies on its side so its "top" is the animal's back, and every mob has its own atlas. An agent writing pixels into the atlas directly has to carry that map in its head and gets it wrong in ways it cannot see.

In Texel the compiler owns the map. Each layout is data: its parts as boxes with sizes and UV origins, which parts are mirrored, which lie turned, and which are cut out by transparency. The agent addresses rightArm.front in the face's own coordinates, and the compiler maps every pixel to its place in the atlas. The review, the sheet views, the 3D preview, import and diff read the atlas back through the same map. That turns a spatial task the agent is bad at into a symbolic one it is good at: naming parts, choosing colors, ordering layers, and acting on errors that point at a line of JSON.

Compilation is deterministic. The only randomness is in noise and material, and both use a seeded generator (the seed defaults to the layer's position), so the same spec gives the same PNG, byte for byte. That makes a spec something that can be reviewed in a diff, kept in version control and regenerated in a build.

The code is in src/core (compiler, layouts, review, views, PNG encoding and decoding; no dependencies and no DOM), src/mcp (the server and the MCP App viewer), src/cli, and src/live (live sessions and the update check). The MCP server depends on @modelcontextprotocol/server and zod; the CLI has no dependencies.

Measurements

Measured on an AMD Ryzen 5 7600 (12 threads), Windows 11, Node 22.13.1, with npm run measure (scripts/measure.ts): each of the 13 bundled examples was compiled 210 times in one process, the first 10 runs as warm-up, and the table shows the median of the other 200. "Compile + PNG" is the spec text to an encoded PNG. "Full render" is what texel_render computes: compile, the full review with art checks and advice, the review sheet and both PNGs. Spec size is the example file minified with JSON.stringify; PNGs are encoded at zlib level 9, as the tools do.

Across the examples the median is 1.54 ms to compile and encode and 16.5 ms for a full render. Startup of the MCP server and the transfer of the sheet image to the client are not included.

A spec is not smaller than the image it produces: the median minified spec is 1.33 times the size of its PNG, between 1 058 and 3 272 bytes. At a rough 4 bytes per token that is about 265 to 820 tokens per spec; this was not checked with a tokenizer, and JSON usually takes more tokens per byte than prose. The point of the format is not size. A PNG is compressed binary an agent cannot write or edit by hand, while each line of a spec is a decision that can be read, patched and reviewed.

Determinism was checked three ways. Within one process, all 210 runs of each example produced byte-identical PNGs (one distinct SHA-256 per example). A second process gave the same 13 hashes. The CLI, built and installed from the packed npm tarball, produced the same hashes for the four examples that were compared (explorer, knight, creeper, ember-blade). All of this ran on one Windows machine; the CI workflow runs the same test suite on Linux, but identical bytes across operating systems have not been compared directly.

Other counts at version 0.7.0 (0.8.0 adds no layouts or operations): 13 example specs and 1 example family (6 members), 26 layouts plus 25 aliases (husk, stray, elytra, zombified_piglin, mooshroom and others), 17 operations, and 113 tests in 10 files.

Limitations

• Java Edition only. Bedrock skins and Bedrock geometry are not supported.
• Only the vanilla box models. There are no custom 3D models or geometry, no HD skins (textures are the vanilla sizes) and no emissive maps.
• Layouts follow the Java Edition 1.21 model code: the UV maps were taken from 1.21.4 and 1.21.11 and checked by running vanilla textures through the views. Other versions are not checked. Mobs without a layout (horses, llamas, fish and many others) cannot be painted yet.
• The views and the 3D preview only model 90° turns. Tilted parts, such as the hoglin's head or the witch's hat, are drawn untilted.
• A family can recolor, switch layers on and off and append layers, but it cannot change or remove a layer of the base, so its members share one design: closer to a set of uniforms than a cast of different characters.
• The art score and the craft advice are heuristics. They have not been validated against human judgment, and they say nothing about whether the texture matches the brief. How good a texture looks depends mostly on the agent writing the spec.
• texel_share, texel_pull and the short links need texel.dev.br: share links are stored there. Long #z= links work without the site's storage. Live sessions don't: the local server serves its own page, and the site's studio is only needed to edit a session. TEXEL_SITE points all of this at another origin.
• Once a day the CLI and the server ask texel.dev.br for version.json to tell the agent about a newer release. The request waits at most 1.5 s, carries no data about the user or the specs, and is skipped when TEXEL_NO_UPDATE_CHECK=1 or CI is set.

Building and testing

You need Node 20 or later.

npm installnpm run typecheck        # tsc --noEmitnpm test                 # vitest: 113 tests, including spawned CLI and MCP server bundlesnpm run build            # dist/texel-mcp.mjs and dist/texel.mjs (the npm package)npm run build:plugin     # plugin/server/texel-mcp.mjs and its THIRD_PARTY_NOTICES.mdnpm run measure          # the numbers in Measurements

The npm build keeps the MCP SDK and zod as dependencies. The plugin build bundles them into one file, because a Claude Code plugin has no install step; it is committed, and CI fails if it no longer matches the source. Docs, examples, schemas and the viewer are embedded in both builds. SITE_URL at build time changes the site origin baked into the builds and the docs.

Bump the version in package.json, plugin/.claude-plugin/plugin.json and the skill's metadata.version together, and add a CHANGELOG.md section for it; a test checks both.

License

MIT, see LICENSE. The plugin's single-file server bundles the MCP TypeScript SDK (Apache-2.0, with parts under MIT) and zod (MIT); their licenses are in plugin/server/THIRD_PARTY_NOTICES.md.

Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.