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

Sign up at ludo.ai and get your API key from app.ludo.ai.

2. Configure Your MCP Client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor

Add to your MCP settings in Cursor preferences:

{
  "mcpServers": {
    "ludo": {
      "url": "https://mcp.ludo.ai/mcp",
      "headers": {
        "Authorization": "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.

Legacy models - 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

---

3D Model Generation (create3DModel)

Convert a 2D image to a 3D GLB model with textures.

Returns: model_url (GLB file) + 4 snapshot images from different angles

Credits: 3 per model Processing time: 60-120 seconds

---

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.2 per generation (one charge returns all variants; introductory price, 80% off the 1-credit list 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. The model must have a humanoid-template rig: rig it with rig_type humanoid_template or humanoid_template_hands first. Only presets that expose a clip_url in listAnimationPresets can be applied.

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.2 per retarget Processing time: 30-90 seconds

---

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 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, with a per-model floor - Hydra: 3/sec (shortest 3s, so 9 minimum; the default 3s = 9); Forge and Forge Pixel: 1.5/sec with a 4-credit minimum (3s = 4.5). Legacy: 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. 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), forge or forge-pixel - 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.

Returns: same shape as animateSprite (spritesheet_url, video_url, audio_url on hydra, gif_url, num_frames, num_cols, num_rows, duration, ...)

Credits: same as animateSprite - Hydra 3/sec (3s = 9); Forge / Forge Pixel 1.5/sec with a 4-credit minimum (1s–2.5s = 4, 3s = 4.5, 4s = 6) Processing time: 30-90 seconds

---

Animation Presets (listAnimationPresets)

List available animation presets, used by transferMotion (onto a sprite) and animate3DModelPreset (onto a rigged 3D model). Returns preset animations, perspectives, and directions; no video URLs are exposed.

Returns:

• animations: Array of presets with id, name, category, description, duration, preview_url, and clip_url on the presets that can be retargeted onto a rigged 3D model
• perspectives: Array with id, name, description (all animations support all perspectives)
• directions: ["N", "NE", "E", "SE", "S", "SW", "W", "NW"] (all animations support all directions)

Credits: Free

---

Motion Transfer (transferMotion)

Transfer motion from a video or animation preset onto a static sprite, producing an animated spritesheet. Use it when you want an exact motion copied - a standard walk or attack cycle from listAnimationPresets, or your own clip; use animateSprite to describe the motion in text instead.

Returns: same shape as animateSprite (spritesheet_url, video_url, audio_url on hydra, gif_url, individual_frame_urls, spritesheet_with_background_url, individual_frame_with_background_urls, num_frames, num_cols, num_rows, duration)

Credits: rate × seconds - Hydra (default): 3/sec (the default 3s = 9); Forge / Forge Pixel: 2/sec with a 4-credit minimum (1.5s = 4, 3s = 6). Legacy Tango: 4/sec. The produced length follows the reference clip, and you are never charged for more than you requested

---

Edit Spritesheet (editSpritesheet)

Edit a spritesheet you previously generated: re-prompt its animation, outpaint beyond the frame (zoom out), or repair a bad loop. Pass back the spritesheet_url you received from animateSprite, animateSpriteKeyframes, transferMotion, or an earlier edit; it must be a spritesheet you generated in the last 7 days (external URLs are not accepted). Omit duration, frames, frame_size, crop and model to keep the source spritesheet's values.

Returns: same shape as animateSprite (spritesheet_url, video_url, gif_url, num_frames, num_cols, num_rows, ...). Audio is generated only by prompt edits on hydra; a fix on a hydra sheet comes back without audio_url

Credits: fix_loop and outpaint: flat 1 credit per second of output, no minimum, model ignored (a 3s sheet = 3). prompt edits: per model - Hydra 3/sec (3s = 9), Forge / Forge Pixel 2/sec with a 4-credit minimum (3s = 6)

---

Spritesheet Sound Effect (createSpriteAudio)

Generate a sound effect for a spritesheet animation you previously generated. Spritesheets made with hydra already come with audio_url, so call this for forge / forge-pixel output, or to replace hydra's sound.

Returns: url of the generated audio file. The audio is also attached to the spritesheet, so it shows up as audio_url on that item in listGenerations

Credits: 3 per call

---

Video Generation (createVideo)

Generate short videos from a source image and a motion prompt (image-to-video). A source image is required: to make a video from text alone, first createImage and animate that, or use createVideoFromReferences. Both current models generate a soundtrack, so no separate audio step is needed.

Returns: url, duration, has_audio

Credits: rate × seconds - Griffin: 1.5/sec (the default 5s = 7.5); Griffin HD: 2/sec (5s = 10). Legacy: Blitz 1/sec, Eagle 1.3/sec, Eagle with Audio 1.8/sec.

---

Video from References (createVideoFromReferences)

Generate a video from 1-5 reference images and a text prompt. Unlike createVideo, which animates a single source image, this composes a new scene that borrows characters, objects, and style from the references.

Returns: url, duration, has_audio

Credits: rate × seconds, higher than createVideo for the same model - Griffin: 2.5/sec (the default 5s = 12.5); Griffin HD: 4/sec (5s = 20). Legacy: Eagle 1.5/sec, Eagle with Audio 2/sec.

---

Edit Video (editVideo)

Edit a video you previously generated with a text prompt and optional reference images (video-to-video). Pass back the url you received from createVideo, createVideoFromReferences, or an earlier edit; it must be a video you generated in the last 7 days (external URLs are not accepted).

Returns: url, duration, has_audio

Credits: Griffin HD: 2 credits/sec (5s = 10)

---

Upscale Video (upscaleVideo)

Upscale a video you previously generated to twice its resolution (2x). Pass back the url you received from createVideo, createVideoFromReferences, or editVideo; it must be a video you generated in the last 7 days (external URLs are not accepted). Both dimensions of the source must be under 960 pixels: griffin (480p) output qualifies, griffin-hd (720p) output does not (landscape or portrait), so generate on griffin if you intend to upscale. A too-large source fails the job and the held credits are refunded.

Returns: url (2x width and height, same duration), duration, has_audio

Credits: Flat rate by duration, independent of model: 0.2 credits/sec (5s = 1)

---

Sound Effect Generation (createSoundEffect)

Generate game sound effects from text descriptions.

Credits: 2 per sound

---

Ambiance Generation (createAmbiance)

Generate ambient soundscapes and background atmospheres from text descriptions.

Credits: 2 per generation

---

Music Generation (createMusic)

Generate background music and themes.

Credits: 3 per track

---

Audio Transform (createAudioTransform)

Remix or transform an existing audio sample using a text prompt.

Documentation truncated — see the full README on GitHub.