Ludo MCP Server

Ludo AI MCP Server

Generate game assets using AI through the Model Context Protocol (MCP).

Features

Quick Start

1. Get an API Key

API access comes with the Pro and Studio plans. Create a key at app.ludo.ai/api-keys; it is shown only once.

Using a coding agent (Claude Code, Codex, Cursor)? The Ludo CLI is the better fit: the agent loads only the commands it needs, and files go in and out by path.

2. Configure Your MCP Client

The server speaks Streamable HTTP at https://mcp.ludo.ai/mcp. Every client sends the key in a header:

Authorization: ApiKey YOUR_API_KEY

Setups for eleven clients, including Windsurf, Cline, Zed and Kiro, are on ludo.ai/developers/mcp.

Claude Code

claude mcp add --transport http ludo https://mcp.ludo.ai/mcp --header "Authorization: ApiKey YOUR_API_KEY"

Add -s user to use it in every project.

Claude Desktop and claude.ai

Open Customize > Connectors, click Add, then Add custom connector. Name it Ludo, use the URL https://mcp.ludo.ai/mcp, and under Request headers add Authorization: ApiKey YOUR_API_KEY. (claude_desktop_config.json only starts local servers; a remote server goes in as a connector.)

Codex

Add to ~/.codex/config.toml:

[mcp_servers.ludo]
url = "https://mcp.ludo.ai/mcp"

[mcp_servers.ludo.http_headers]
Authorization = "ApiKey YOUR_API_KEY"

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "ludo": {
      "url": "https://mcp.ludo.ai/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_API_KEY"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json, then use Copilot Chat in Agent mode. VS Code asks for the key once and stores it securely:

{
  "inputs": [
    { "type": "promptString", "id": "ludo-api-key", "description": "Ludo.ai API key", "password": true }
  ],
  "servers": {
    "ludo": {
      "type": "http",
      "url": "https://mcp.ludo.ai/mcp",
      "headers": { "Authorization": "ApiKey ${input:ludo-api-key}" }
    }
  }
}

Gemini CLI

gemini mcp add -s user --transport http --header "Authorization: ApiKey YOUR_API_KEY" ludo https://mcp.ludo.ai/mcp

Clients that only run local servers

Bridge with mcp-remote (needs Node.js). Keep the header argument free of spaces and pass the key through env:

{
  "mcpServers": {
    "ludo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.ludo.ai/mcp", "--header", "Authorization:${LUDO_AUTH}"],
      "env": { "LUDO_AUTH": "ApiKey YOUR_API_KEY" }
    }
  }
}

Available Tools

Generation tools run on a job queue and return a job id immediately; the Returns field of each tool below describes the result you get back from getApiJob once the job succeeds. See How Generation Calls Work.

Models

Sprite animation, motion transfer, spritesheet editing and video generation take an optional model. Pick from the current models; the defaults are what the Ludo web app uses.

griffin (480p) was retired from video generation and video from references on 2026-10-27. Requests that name it are rejected; use griffin-hd.

Legacy models - hydra-plus (since 2026-11-02), blitz, eagle, eagle-audio, tango (and the alias standard) - are still accepted so existing integrations keep working, but they are scheduled for removal. Do not use them for new work. The server marks them LEGACY in every tool description and lists them last.

Search Documentation (searchDocs)

Ask Ludo's own documentation a plain-language question and get back only the few sections that answer it: how to choose a sprite animation mode, when to use Generate Before / Generate After, how margins behave, which model suits a job, what something costs, and each generator's known limitations. This is the fastest way to learn how a feature is meant to be used before generating with it, so start here rather than reading whole documents.

Returns:

• results: Array of { doc, label, section, relevance, content }, best first. content is the section's full markdown; doc and section can be passed straight to getDocs to read it again. relevance is a 0-1 match score, and only results scoring 0.6 or higher are returned
• message: Present only when results is empty, which means the documentation does not cover the question. Rephrase it, or browse with getDocs

If the search backend is briefly unavailable the tool returns 503; fall back to getDocs rather than retrying in a loop.

Credits: Free

---

Feature Documentation (getDocs)

Browse or read Ludo's documentation in full. This is the same documentation the Ludo web app shows its users, so it occasionally describes buttons rather than parameters; the substance applies here just the same. To answer a specific question, use searchDocs first.

Call it with no parameters to get a table of contents, then again with doc (and ideally sections) to read only what you need. The whole corpus is roughly 280,000 characters, so fetching a full document without naming sections can return tens of thousands of characters.

Returns:

• docs: Array of { id, label, sections }, where each section is { title, content }. content is markdown, and is omitted from the table of contents
• unmatched_sections / available_sections: Present only when some, but not all, requested titles matched: the titles that matched nothing, and every valid title of doc

An unknown doc, or a request where no section title matches, returns 400 listing the valid values, so a wrong guess costs one extra call rather than a dead end.

The server also announces both documentation tools to MCP clients via its instructions field during the initialize handshake, so models connected through clients that surface server instructions are told to search the documentation before generating.

Credits: Free

---

Image Generation (createImage)

Generate sprites, icons, backgrounds, UI assets, and textures from a text prompt alone (no source image needed). To match the art style of an existing image use generateWithStyle, to modify an existing image use editImage, and to cut out a subject use removeBackground.

Credits: 0.5 per image

---

Edit Image (editImage)

Modify an existing image using text instructions (smart editing).

Credits: 0.5 per image

---

Generate with Style (generateWithStyle)

Generate new content while maintaining the visual style of a reference image.

Credits: 0.5 per image

---

Generate Pose (generatePose)

Generate a new pose for an existing sprite. Use this BEFORE animateSprite to get the best animation results - the starting pose should match your intended animation.

Returns: url, pose, motion_prompt

Example workflow:

1. Generate a "Walk (Left)" pose with generatePose
2. Use the returned motion_prompt directly in animateSprite for optimal animation results

Credits: 0.5 per image

---

Rotate Sprite (rotateSprite)

Rotate the camera view of an existing sprite to a new angle, keeping the same character and pose. Useful for generating turnaround / directional views of a sprite.

Returns: url, camera_rotation, camera_elevation

Credits: 0.5 per image

---

Remove Background (removeBackground)

Remove the background from a single image, returning the subject isolated on a transparent background. For broader edits (not just cutting out the subject), use editImage instead.

Returns: a single result with url (transparent PNG)

Credits: 0.5 per image

---

Upscale Image (upscaleImage)

The same image at a higher resolution, up to 4x, with the result capped at 2048px on its longest side. The source must be below 2048px on its longest side; a larger one is rejected with HTTP 400 before anything is charged.

Returns: a single result with url

Credits: 0.5 per image

Convert to Pixel Art (convertToPixelArt)

Any art, broken AI pixel art or pixel art comes back as pixel art at about the input's own size. Synchronous: the call answers with the result directly, with no job to poll.

Returns: url, pixel_size (yours, or the detected one, which can be fractional), and columns / rows, the art's size in pixel-art pixels: resize to columns x rows with nearest-neighbour for one image pixel per art pixel

Credits: Free (20 calls per 5 minutes, 120 an hour, 1,000 a day)

---

3D Model Generation (create3DModel)

Convert a 2D image to a 3D GLB model with textures, optionally rigged in the same call.

Returns: model_url (GLB file), snapshot images from different angles, and rigged

Credits: 4 per model with prop, 15 with hero; rig adds 1, charged only when the model comes back rigged Processing time: 60-120 seconds with prop; hero is slower

---

Image for a 3D Model (create3DModelImage)

A character image ready for create3DModel, the first step of Directional Sprites on the web. create3DModel converts the image it is given as it is; this makes one for it first. Pass a prompt, your own image, or both: an image is redrawn as a 3D render, and the prompt then says what to change. A redraw is a new picture each time, so call again for another try.

Returns: a single result with url, to pass as create3DModel's image

Credits: 0.5 per image

---

Rig 3D Model (rigModel)

Generate a skeleton and skin weights for an existing 3D model so it can be animated. Non-destructive to the geometry: it returns a new rigged GLB. Rig a model before using animate3DModel.

Returns: model_url (rigged GLB, skeleton + skin weights baked in), rigged (true)

Credits: 1 per rig Processing time: 60-120 seconds

---

Animate 3D Model (animate3DModel)

Generate text-driven skeletal animations for an already-rigged 3D model (rig it first with rigModel). Animation quality is hit-or-miss, so several candidates are returned for you to choose from. Each candidate is a standalone animation-only GLB (skeleton + one clip, no mesh) plus an mp4 preview; pick the best one and fuse it onto your model in a game engine or three.js.

Returns: animations, an array of candidates, each with clip_name, glb_url (animation-only GLB), preview_url (mp4), mode, seed, motion, fit_rmse

Credits: 0.5 per generation (one charge returns all variants; promotional price) Processing time: 60-120 seconds

---

Animate 3D Model from Preset (animate3DModelPreset)

Apply a curated animation preset to an already-rigged 3D model (retargeting). Unlike animate3DModel, the motion comes from a professionally curated clip library instead of a text prompt, so exactly one clip is returned. Any rig type can take a preset (rig the model first with rigModel, or create3DModel with rig: true), though retargeting does not succeed on every model; when it does not, the job returns an error. Any preset id from listAnimationPresets works.

Returns: animations, the same envelope as animate3DModel, containing one clip with clip_name, preset_id, glb_url (animation-only GLB, joints named as on your model), preview_url (mp4), seed, motion, fit_rmse

Credits: 0.5 per retarget Processing time: 30-90 seconds

---

Directional Sprites

Render a 3D model as styled sprites seen from up to 8 directions (where the camera stands around a character facing S). Every direction asked for in one call is rendered together, on the same frame size, scale and floor, so the sprites line up. The usual flow:

1. (Optional) A character image: create3DModelImage from a prompt, or your own image redrawn as a 3D render.
2. A rigged model: create3DModel with that image and rig: true (or rigModel for a model you already have). Any rig type can take an animation preset, though retargeting does not succeed on every model.
3. (Optional) An animation, at most one: a preset_id from listAnimationPresets, or an animation_url made for this model by animate3DModelPreset or animate3DModel. With none, the sprites are a still pose.
4. (Optional) Accessories: fitDirectionalAccessory for each item (a sword, a shield, a helmet...), adjusted until it looks right, then attachDirectionalAccessories for one model holding them all. Use its model_url as model from here on.
5. listDirectionalSpriteStyles: pick a look.
6. previewDirectionalSprites: check it, free.
7. createDirectionalSprites for animated spritesheets, or createDirectionalStills for still images.

fitDirectionalAccessory

Fit one item GLB to a rigged model, held by one bone: a hand, the head, the back or the hips. The item is first placed automatically for its kind (a sword by its handle, a gun by its pistol grip, a shield on the forearm, a helmet over the head, a backpack on the back), and the hand closes round it. Adjust it relative to that automatic fit and call again until it looks right: each call starts from the automatic fit, so send the full adjustment every time. Nothing is saved. Free and synchronous (not a job): a few seconds with previews, about a second without.

Returns: the fit as applied (kind, point, bone, size, move, turn, flip, grip), the placement to pass to attachDirectionalAccessories, checks (how far the item sinks into the body, how far its grip is from the palm, how much of the head pokes through a helmet), points (this skeleton's attach points) and, unless preview is false, model_url (the model holding the item, kept 7 days) and previews (4 walking frames each from SW and SE). Previews share previewDirectionalSprites' one-at-a-time slot; when they could not be made, preview_error says why and the fit is still valid.

Credits: Free (30 calls per 5 minutes, 200 an hour, 1,000 a day)

attachDirectionalAccessories

Put up to 8 items on the model, each at the placement fitDirectionalAccessory returned (or, without one, at the automatic fit plus the same kind / point / bone / size / move / turn / flip / grip adjustments). At most one item closes each hand: the first one listed. Free and synchronous.

Returns: model_url (one GLB of the model holding every item, kept 7 days: pass it as model to previewDirectionalSprites, createDirectionalSprites or createDirectionalStills), saved (whether the items were saved on your model, which replaces its previous items and shows them in the Ludo web app's Directional Sprites) and items

Credits: Free (20 calls per 5 minutes, 300 a day)

listDirectionalSpriteStyles

Free. Returns styles (each with id, label, description, family, pixel, thumbnail_url, version and its settings / advanced_settings: a name, kind of choice, bool or color, options and default), plus the perspectives and directions to choose from.

previewDirectionalSprites

A few frames of the model in a style, from each direction asked for, to check a look before rendering. Synchronous (not a job) and free; nothing is saved to your generations. Returns previews, one per direction: frame_urls (transparent images: 4 frames when animated, 1 for a still model), width, height, num_frames, fps and render_3d (the style and settings as rendered). An account runs one preview at a time: starting another cancels the one still running, which then answers with no body (HTTP 204). Takes the model, animation, camera and style parameters below, and target_frame_size (32-384, default 256).

createDirectionalSprites

At most one of animation_url, preset_id and model_animation; with none, each sheet is a single frame.

Returns: sheets, one per direction in the order asked, each with direction, spritesheet_url, video_url, num_frames, num_cols, num_rows, fps, render_3d, and gif_url / individual_frame_urls when asked

Credits: 1 per direction

createDirectionalStills

The model as it is, one large transparent sprite image per direction, ready for animateSprite or editImage. Takes model, perspective, directions, style_id, style_params, style_version and request_id as above.

Returns: images, one per direction, each with direction, url, width, height and render_3d

Credits: 0.5 per direction

---

Sprite Animation (animateSprite)

Create animated spritesheets from static images. Use this when you can describe the motion in text; use transferMotion to copy an exact motion from a reference video or a named preset, and generatePose first when the source image is not yet in the pose the animation should start from.

Returns: spritesheet_url (the sheet), video_url (an mp4 of the animation - pass it to transferMotion as video or to createSpriteAudio as spritesheet_video_url), audio_url (hydra and hydra-plus only: URL of a generated sound effect (mp3), so there is no need to call createSpriteAudio), num_frames, num_cols, num_rows, duration (seconds, to play the sheet at its real speed), and when requested gif_url, individual_frame_urls, spritesheet_with_background_url, individual_frame_with_background_urls

Credits: rate × seconds - Hydra: 3/sec (shortest 3s, so 9 minimum; the default 3s = 9); Forge and Forge Pixel: 1.5/sec, no minimum (3s = 4.5). Griffin: flat 10 per animation. Legacy: Hydra+ 4/sec (shortest 3s, so 12 minimum); Blitz 1.9/sec, Eagle 2.6/sec, Eagle with Audio 3.1/sec, all with a 4-credit minimum. Processing time: 30-90 seconds

Writing the motion prompt

Applies to animateSprite and animateSpriteKeyframes.

• Describe exactly and unambiguously what the character should do. Specific or complex actions are fine; there is no need to simplify them.
• Don't over-describe: too much detail can harm the animation. Name an action the model already knows instead of breaking it into steps ("walking", never "move the left foot forward, then the right foot").
• Don't restate what the image or keyframes already show (the character, its equipment, the art style, background, lighting, camera). Leave frame count and timing to frames and duration.
• Negative phrasing ("no background", "do not move the camera", "without a weapon") works only on hydra and hydra-plus. On forge, forge-pixel and the legacy models it backfires: naming something you don't want makes it more likely to appear. On those models state only what should happen.

---

Keyframe Animation (animateSpriteKeyframes)

Animate a sprite through up to three fixed keyframes (initial_image, middle_image, final_image), producing a spritesheet that interpolates through the provided frames in order. Runs on hydra (default), griffin-hd, forge or forge-pixel (and the legacy hydra-plus) - the models that support a middle keyframe. The motion prompt is optional here: when omitted, the motion is derived purely from the keyframes. For just a start and end frame, animateSprite with final_image does the same job.

Documentation truncated — see the full README on GitHub.