Efecto MCP Server

Model Context Protocol (MCP) server for programmatic poster creation with Efecto.

Create stunning visual designs with ASCII effects, glitch art, halftone patterns, animated text, and more—all from your CLI or AI agent.

Quick Start

Install and set up:

``bash
npx @efectoapp/mcp-server install
`

Then restart Claude Code and you're ready to go!

$3

Ask Claude:
> "Use efecto to list available effects"

$3

`bash
claude mcp add efecto -- npx @efectoapp/mcp-server
`

Example Workflow

> "Make a cyberpunk image that says DOPE for Instagram"

`
1. search_images({ query: "cyberpunk", orientation: "vertical" })
→ Returns images from Lummi

2. create_poster({ aspectRatio: "9:16" })
→ Creates Instagram story format

3. set_background({ type: "image", imageUrl: "" })
→ Sets the cyberpunk image as background

4. apply_effect({ effectId: "glitch-digital" })
→ Applies digital glitch effect

5. add_postprocess({ type: "chromatic-aberration", strength: 0.02 })
→ Adds RGB split effect

6. add_postprocess({ type: "scanlines", intensity: 0.3 })
→ Adds CRT scanlines

7. add_layer({ type: "text", content: "DOPE", fontSize: 120, fontFamily: "Space Grotesk", color: "#ffffff", animationType: "glitch", animationSpeed: 2 })
→ Adds animated glitch title text

8. generate_url()
→ Returns shareable URL like https://efecto.app/canvas?lm=1&...
`

Available Tools

$3

| Tool | Description |
|------|-------------|
| list_effects | List all available main effects |
| list_fonts | List available fonts for text layers |
| list_palettes | List color palettes |
| list_materials | List 3D materials |
| list_postprocess | List post-processing effects |
| list_text_animations | List text animation types and parameters |

$3

#### search_images

Search for free stock images from Lummi.

| Parameter | Type | Description |
|-----------|------|-------------|
| query | string | Search query (e.g., "cyberpunk", "nature"). Empty = featured |
| orientation | string | "vertical" (9:16), "horizontal" (16:9), "square" (1:1) |
| type | string | "photo", "illustration", "3d" |
| luminance | string | "dark", "neutral", "bright" |
| limit | number | Max results (default: 10, max: 50) |

$3

#### create_poster

Create a new poster.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| aspectRatio | string | "16:9" | "16:9", "9:16", "1:1", "4:3", "full" |
| backgroundColor | string | "#1a1a1a" | Background color (hex) |

#### set_background

Set the background layer (always at index 0).

| Parameter | Type | Description |
|-----------|------|-------------|
| type | string | "solid" or "image" |
| color | string | Hex color (for solid type) |
| imageUrl | string | Image URL (for image type) |

#### add_layer

Add a layer to the poster.

| Parameter | Type | Description |
|-----------|------|-------------|
| type | string | "text", "image", "video", "3d" |
| name | string | Layer name |

Text layer parameters:
- content: Text content
- fontFamily: Font name (e.g., "Space Grotesk", "Inter")
- fontSize: Size in pixels
- fontWeight: "normal", "medium", "semibold", "bold"
- color: Hex color
- textAlign: "left", "center", "right"

Text animation parameters (optional):
- animationType: Animation type (see below)
- animationSpeed: Speed multiplier (0.1-5.0)
- animationAmplitude: Intensity (0-100)
- animationStaggerDelay: Delay between characters in ms (0-500)
- animationStaggerMode: "sequential", "random", "center-out", "edges-in"
- animationLoop: Loop the animation (default: true)

Animation types: wave, rotate, scale, orbit, bounce, shake, spiral, typewriter, glitch, elastic, cascade, neon

Each animation type has additional specific parameters. Use list_text_animations to see all options.

Image/Video layer parameters:
- mediaUrl: Media URL
- objectFit: "cover", "contain"

Transform parameters (all layers):
- x, y: Position (-1 to 1, 0 = center)
- width, height: Size (0 to 1+, 1 = full canvas)
- rotation: Degrees
- opacity: 0-1

#### modify_layer

Modify an existing layer by ID.

#### remove_layer

Remove a layer by ID (cannot remove background).

#### apply_effect

Apply the main effect. Only one can be active.

| Parameter | Type | Description |
|-----------|------|-------------|
| effectId | string | Effect ID (see below) |
| enabled | boolean | Enable/disable (default: true) |

Available Effect IDs:

| Category | Effect IDs |
|----------|------------|
| ASCII | ascii-standard, ascii-blocks, ascii-braille, ascii-hatching, ascii-matrix, ascii-technical, ascii-dense, ascii-minimal |
| Dither | dither-floyd-steinberg, dither-atkinson, dither-jarvis-judice-ninke, dither-stucki, dither-burkes, dither-sierra, dither-two-row-sierra, dither-sierra-lite |
| Halftone | halftone-mono, halftone-cmyk |
| Glitch | glitch-chromatic, glitch-digital, glitch-vhs, glitch-weird |
| Art | art-kuwahara, art-crosshatch, art-lineart, art-engraving, art-stipple |

Effect-specific parameters:
- ASCII: cellSize (4-32), color (bool), invert (bool)
- Dither: pixelation (1-10), colors (array)
- Halftone: dotSize
- Glitch: speed

#### add_postprocess

Add a stackable post-processing effect.

| Parameter | Type | Description |
|-----------|------|-------------|
| type | string | Post-process type (see below) |
| enabled | boolean | Enable/disable |

Post-process types: scanlines, vignette, chromatic-aberration, curvature, grain, noise, pixelate, wave, rgb-glitch, brightness-contrast, color-tint, palette, jitter, bloom, dot-screen, sepia, grid, light-beams, motion-blur

Common parameters by type:
- scanlines: intensity, count
- vignette: intensity, radius
- chromatic-aberration: strength, angle
- grain: intensity, size, speed
- brightness-contrast: brightness, contrast, saturation, hue
- palette: colors (array), intensity

#### get_state

Get the current poster state as JSON.

$3

#### generate_url

Generate a shareable URL for the current poster.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| baseUrl | string | "https://efecto.app" | Base URL |

Returns a URL that opens in any browser with all effects applied.

#### render_image

Render the poster to an image (async).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| format | string | "png" | "png", "jpeg", "webp" |
| width | number | auto | Output width |
| height | number | auto | Output height |
| quality | number | 90 | JPEG/WebP quality |

Returns a job ID for polling status.

Development

`bash
pnpm install # Install dependencies
pnpm build # Build TypeScript
pnpm dev # Watch mode
pnpm start # Run server
`

API Endpoints

The MCP server calls these Efecto API endpoints:

| Endpoint | Method | Description |
|----------|--------|-------------|
| /api/v1/images/search | GET | Search Lummi images |
| /api/v1/state/encode | POST | Encode state to URL |
| /api/v1/state/decode | POST | Decode URL to state |
| /api/v1/state/validate | POST | Validate state |
| /api/v1/render` | POST | Render to image |

License

MIT