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, 68 other textures, all in the Java Edition 1.21 texture layouts: 57 mob textures (zombies, skeletons, creepers, horses, llamas, foxes, bees, axolotls, illagers, wardens, golems and more), armor layers, capes with elytra, items, blocks with their top and side files (logs, grass, furnaces), plants, GUI sprites, particles and paintings. Textures can animate and glow, and a set of specs builds a resource pack that Texel also checks.

Texel is open source (MIT) and in development, at version 0.9.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.

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.mjs
3. Check that it runs: node --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 --workspace
• Any other client: add this to its MCP configuration, keeping the servers already there: {"mcpServers": {"texel": {"command": "node", "args": [" ", "--workspace", " "]}}}

1. 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, pack, check-pack, share, pull, live, format, layouts and init. Exit codes: 0 done, 1 the spec, family or pack has errors, 2 bad usage.

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 18 operations. Twelve are plain drawing (fill, rect, clear, pixels, points, line, gradient, pattern, noise, shade, copy, mirror), one fixes symmetry (symmetrize) and five are higher level: material (fabric, leather, metal, fur, knit and other surfaces), face, hair, lighting and bevel (raised and inset frames in the vanilla GUI style). Any operation marked "emissive": true also paints the texture's glow map, _eyes.png.

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. The same patches make animation frames ("animation": { "frames": [{}, { "patch": [...] }] } compiles to a strip and its .png.mcmeta, or one file per frame for particles) and family members: a family expands one base spec into variants or a matrix of axes (teams, ranks, factions) by swapping palettes, turning layers on and off, patching base layers by id and appending layers, so its members can be different characters, not only recolors. An existing PNG can be imported into an editable spec, one layer per painted face, and import --pixelize first turns any picture (concept art, an HD skin) into a texture of the layout's size.

asset says where a texture goes in a resource pack (mobs default to the vanilla file they replace). pack builds the pack from specs and families, with pack.mcmeta for a Minecraft version (1.21 to 1.21.11) and, on request, the models, block states and item definitions a new item or block needs; check-pack checks any pack: its format and versions, file names, PNGs, .mcmeta animations and GUI scaling, entity texture sizes, references to missing models or textures and unused textures.

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 19 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. Codes are stable across releases and listed with their meaning in docs/spec.md (ISSUE_CODES in code); a test keeps the list equal to what the source can report. Block textures also get their tiling measured: how much harder each edge breaks than the texture's own neighbors where copies meet (stats.seams, tile-seam). 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