LPC Character Generator — MCP

English · Português

An MCP server that builds LPC pixel-art character spritesheets — the same parts as the Universal LPC Spritesheet Character Generator — and exports them ready for Godot, Unity and the web (Phaser/PixiJS).

Ask in plain language ("make a tanned blacksmith with a leather apron and a hammer") and your assistant assembles the character, shows an animated preview in the chat and saves the files.

Installation

You need uv and Git. uv fetches the right Python and the package by itself — nothing to clone, no dependencies to install.

1. Install uv (once):
   • Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Prepare the server (downloads the item definitions, ~10 s, only once):

   uvx lpc-character-mcp --setup
   

3. Register it in your assistant (below). The command is always uvx lpc-character-mcp.

To run the latest code straight from GitHub, replace uvx lpc-character-mcp with uvx --from git+https://github.com/kyuza1/lpc-character-mcp lpc-character-mcp in any example.

Characters are saved to ~/lpc-characters (on Windows, C:\Users\<you>\lpc-characters). Set LPC_OUTPUT_DIR to change it — for example, to your Godot/Unity sprites folder. lpc-character-mcp --where prints every folder in use.

Claude Code

claude mcp add lpc --scope user -- uvx lpc-character-mcp

Claude Desktop

Settings → Developer → Edit config (claude_desktop_config.json):

{
  "mcpServers": {
    "lpc": { "command": "uvx", "args": ["lpc-character-mcp"] }
  }
}

Codex (OpenAI)

codex mcp add lpc -- uvx lpc-character-mcp

Or edit ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml):

[mcp_servers.lpc]
command = "uvx"
args = ["lpc-character-mcp"]
startup_timeout_sec = 60

Check with codex mcp list. The same file is used by the Codex VS Code extension.

Antigravity (Google)

In the agent panel click … → MCP Servers → Manage MCP Servers → View raw config and add to mcp_config.json (~/.gemini/config/mcp_config.json; on Windows, %USERPROFILE%\.gemini\config\mcp_config.json):

{
  "mcpServers": {
    "lpc": { "command": "uvx", "args": ["lpc-character-mcp"] }
  }
}

Save and click Refresh on the MCP Servers page. In the Antigravity CLI, use /mcp.

Other MCP clients

Any client that runs stdio servers works with the same uvx lpc-character-mcp command.

Without uv (pip)

pip install lpc-character-mcp
lpc-character-mcp --setup

Then register the lpc-character-mcp command (no arguments) in your assistant.

Tips

• Free disk space: lpc-character-mcp --clear-cache deletes cached images (--clear-cache 30 only those unused for 30 days).
• Update: uvx lpc-character-mcp@latest --version
• App can't find uvx: use the full path (where uvx on Windows, which uvx elsewhere).

Example requests

• "Make a tanned blacksmith with a leather apron and a hammer, export for Godot"
• "Show me an animated preview of him hammering"
• "Generate 10 random villagers with seed 1, with Unity files"
• "Open this link and generate the character: https://liberatedpixelcup.github.io/...#sex=male&body=..."
• "Which aprons have an idle animation for the male body?"

Tools

Example items:

[
  {"id": "body/body", "color": "bronze"},
  {"id": "head/heads/human/heads_human_male"},
  {"id": "hair/short/hair_plain", "color": "dark_brown"},
  {"id": "torso/shirts/longsleeve/torso_clothes_longsleeve", "color": "white"},
  {"id": "torso/aprons/torso_aprons_overalls", "variant": "leather"},
  {"id": "legs/pants/legs_cuffed", "color": "white"},
  {"id": "feet/boots/feet_boots_basic", "color": "brown"},
  {"id": "tools/tool_hammer", "color": ["steel", "walnut"]}
]

Colors

• "color": "blonde" — one color (see colors in get_item).
• "color": ["steel", "walnut"] — multi-part items (head and handle, armor and belt...). Parts are listed in color_parts from get_item; null keeps a part's default.
• Head, ears, nose and other skin items without a color inherit the body color.
• One item per type, like the site: asking for two hairstyles keeps the last one (and says so in warnings).

Where to save

output_dir saves straight into a folder — e.g. your game's sprites folder: "generate the blacksmith in C:/my-game/art/npcs and export for Godot". Otherwise files go to LPC_OUTPUT_DIR or ~/lpc-characters.

Layout and parts

• layout: "standard" (default) — same as the site: 832px wide, every animation always on the same row (walk at y=512, slash at y=768...). Oversized animations go below y=3456.
• layout: "compact" — only the requested animations, stacked.
• split — also saves pieces: "animation" (one PNG per animation), "frame" (one PNG per frame in <name>_frames/<animation>/<direction>_NN.png) and/or "item" (one sheet per item, for swapping outfits in-game). Accepts a list: ["animation", "frame"].

Oversized animations

Big weapons and tools (swords, spears, hammer, axe, bow...) use 128 or 192px frames. They are added automatically when their base animation is requested (asking for slash with the hammer also produces tool_hammer).

Complete animations

Not every LPC item has art for all 15 animations (e.g. the apron has no idle, run, jump...). In those animations the item simply disappears. To avoid surprises:

• Every result warns you. generate_character always returns animation_check:

  "animation_check": {
    "complete": false,
    "incomplete_items": {
      "torso/aprons/torso_aprons_apron": {
        "missing": ["climb", "idle", "jump", "sit", "emote", "run", ...],
        "complete_alternatives": ["torso/aprons/torso_aprons_overalls", ...]
      }
    },
    "summary": "ATENÇÃO: nem todas as animações ficaram completas: Apron não tem ..."
  }
  

  The preview, batches and the web demo warn too.
• prefer_complete: true replaces each incomplete item with the closest item that has every animation, keeping the color (e.g. apron → overalls). Replacements are listed in replaced. The assistant is told to ask you first.
• Search puts complete items first. search_items lists them first, shows missing_animations for the others and accepts complete_only: true. get_item shows what is missing and suggests complete_alternatives.
• Random characters only use complete items.

Not counted as missing: face, nose, beard, glasses and necklaces in climb (the character faces away), expressions in hurt, weapons/tools/shields — which by nature only appear in their own animations (listed in equipment_only_in) — and animations the body itself lacks (listed in body_missing).

Exporting to engines

Pass export to generate_character (you can combine them):

Art credits

Every generation writes <name>_credits.txt and <name>_credits.csv with authors, licenses and links for only the art that was used. The sprites are LPC art (CC-BY-SA 3.0, OGA-BY 3.0, GPL 3.0 and others) — if you ship a game, include these credits.

Limitations

• Some types have no complete version at all (capes, backpacks, dresses, skirts). With prefer_complete they stay as they are and animation_check says so.
• The LPC muscular, child and pregnant bodies lack some animations (e.g. muscular has no shoot or climb); animation_check reports them in body_missing.
• Godot 3 is not supported (Godot 4 only). Unity was tested on Unity 6.
• Runs locally (stdio); it does not work with clients that only accept remote servers.
• Tool messages and warnings are in Portuguese.

Development

git clone https://github.com/kyuza1/lpc-character-mcp.git
cd lpc-character-mcp
pip install -e ".[dev]"
python -m pytest -q

From a clone, definitions, cache and output live inside the clone (lpc/, cache/, output/). Tests run on GitHub Actions on Linux, Windows and macOS on every push and every Monday (to catch changes in the official LPC repository). Releases are published to PyPI automatically when a GitHub release is created. See CHANGELOG.md.

License

Code under MIT. The downloaded art belongs to the LPC artists and follows their licenses (see the generated credits files).