ultramock-mcp

An MCP server that lets an AI agent (Claude Code, Claude Desktop, etc.) create and configure ultramock.io product mockups using your own logged-in subscription.

Ultramock currently renders the final image/video in the browser with WebGL, canvas and video encoder APIs. The public app does not expose a server-side "render and download" endpoint. This MCP covers the operations that can be done headlessly through Ultramock's HTTP APIs: projects, templates, full project payload/config editing, source asset uploads, and authenticated source asset downloads.

Use get_capabilities from an agent to see the current boundary in machine-readable form. A final rendered image/video export still requires either Ultramock to add a server render API or a headless browser automation layer.

Tools

Tool	What it does
get_capabilities	Report which operations work without a browser and why final rendered export does not.
get_status	Fetch the authenticated editor status/account payload exposed by Ultramock.
list_projects	List your projects (id, name, version, editor URL).
get_project	Full config of one project: dial values, full payload, asset keys/URLs, editor URL.
create_project	New project, optionally seeded from a template.
duplicate_project	Copy a project including its config and screen image.
rename_project	Rename a project.
delete_project	Delete a project (permanent).
list_templates	System + your templates (use with create/apply).
apply_template	Apply a template's device/angle/lighting to a project.
update_config	Merge dial values (camera, scene, effects, device, border) into a project.
update_payload	Deep-merge arbitrary JSON into the full project payload, including viewport/timeline/editor settings.
set_screenshot	Upload a local PNG/JPG/WebP as the on-device screen content.
set_scene_screenshot	Upload a local PNG/JPG/WebP and assign it to a specific timeline scene.
set_background_image	Upload a local PNG/JPG/WebP as the project background image.
download_asset	Download source assets (screen image, background, scene screenshot) to a local file.
get_editor_url	The URL to open only when you need visual preview or final rendered export.

Dial keys used by update_config

Pass a dials object of key -> value. Only the keys you pass change.

• camera: Viewport.camera.tiltX, .tiltY, .roll, .fov, .zoom, .panX, .panY, .flap, .flapX
• scene: Viewport.scene.bgMode, .darkMode, .bgColor (hex), .bgImage, .bgBlur, .transparentBg, .envId, .lightHeight, .lightPos, .lift, Viewport.devices.mockupModel
• device: Viewport.devices.mockupBgMode, .mockupBg, .mockupBgImage, .mockupPadding, .iphoneFinish, .statusBar, .hdrYaw, .contactShadow, .iblIntensity, .keyLight, .keyLightHeight, .keyLightRotation
• border: Viewport.border.borderRadius, .borderStyle, .glassWidth
• effects: Viewport.effects.depth, .sharpen, .vignette, .grain, .pixelGrid, .caStrength, .bloom, .bloomStrength, .bloomThreshold, .bloomRadius, .lighting, .lightingAngle, .lightingIntensity, .lightingSoftness, .reflection, .strength
• blur: Viewport.blur.mode, .strength, .falloff, .bokeh, .focusX, .focusY, .focusSize, .angle, .position

Use update_payload for settings stored outside payload.dialValues, such as editorSettings, viewport, timeline.scenes, text/logo scene data and export metadata. Object patches are merged recursively; arrays and scalar values are replaced.

Setup

npm install
npm run build

Get your session token

Auth uses your ultramock login cookie (no separate API key exists).

1. Open https://www.ultramock.io and sign in.
2. DevTools → Application → Cookies → https://www.ultramock.io.
3. Copy the value of __Secure-authjs.session-token (a UUID).

That value is ULTRAMOCK_SESSION_TOKEN. It rotates when you sign out / the session expires (~30 days); refresh it if calls start returning auth errors.

Register with Claude Code

claude mcp add ultramock \
  --env ULTRAMOCK_SESSION_TOKEN=<your-token> \
  -- node /path/to/ultramock-mcp/dist/index.js

Or add it to your MCP config (~/.claude.json / Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "ultramock": {
      "command": "node",
      "args": ["/path/to/ultramock-mcp/dist/index.js"],
      "env": { "ULTRAMOCK_SESSION_TOKEN": "your-token-here" }
    }
  }
}

Optional env: ULTRAMOCK_BASE_URL (defaults to https://www.ultramock.io).

Typical agent flow

1. get_capabilities -> confirm what can be done without a browser.
2. list_templates -> pick a look (e.g. "Realistic iPhone").
3. create_project with fromTemplateId -> get a project id.
4. set_screenshot, set_scene_screenshot or set_background_image -> upload source assets.
5. update_config or update_payload -> tweak camera, background, effects, viewport or timeline data.
6. download_asset -> retrieve source assets again if needed.
7. get_editor_url -> only for visual preview or final rendered image/video export.

Notes

• Writes use Ultramock's lease + optimistic-version model; this server acquires and releases the edit lease for you on each write. If another session holds the lease (e.g. the project is open in a browser tab), the server takes it over and that tab drops to read-only.
• download_asset downloads the source images stored on the project. It does not render the composed mockup.
• Image upload tools accept PNG, JPG/JPEG and WebP files up to Ultramock's 1 MB upload limit.
• I verified the current app behavior against Ultramock's public client bundle: /api/capture and /api/video-authorize authorize exports, while the final image/video bytes are generated in the browser and downloaded from a local blob URL.