# SudoMock MCP server

> Generate photorealistic product mockups from PSD templates or photos using natural language through an AI client.

- Repository: https://github.com/sudomock/mcp-server
- Page: https://hostedmcp.org/servers/sudomock/mcp-server
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 3.12.1

## Install

### Claude Code

```sh
claude mcp add --env 'SUDOMOCK_API_KEY=<YOUR_SUDOMOCK_API_KEY>' mcp-server -- npx -y @sudomock/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@sudomock/mcp"
      ],
      "env": {
        "SUDOMOCK_API_KEY": "<YOUR_SUDOMOCK_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@sudomock/mcp"
      ],
      "env": {
        "SUDOMOCK_API_KEY": "<YOUR_SUDOMOCK_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@sudomock/mcp"],"env":{"SUDOMOCK_API_KEY":"<YOUR_SUDOMOCK_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@sudomock/mcp"
      ],
      "env": {
        "SUDOMOCK_API_KEY": "<YOUR_SUDOMOCK_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp-server --env 'SUDOMOCK_API_KEY=<YOUR_SUDOMOCK_API_KEY>' -- npx -y @sudomock/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp-server]
command = "npx"
args = ["-y", "@sudomock/mcp"]

[mcp_servers.mcp-server.env]
SUDOMOCK_API_KEY = "<YOUR_SUDOMOCK_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'SUDOMOCK_API_KEY=<YOUR_SUDOMOCK_API_KEY>' mcp-server npx -- -y @sudomock/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@sudomock/mcp"
      ],
      "env": {
        "SUDOMOCK_API_KEY": "<YOUR_SUDOMOCK_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `SUDOMOCK_API_KEY` | yes | yes | Your SudoMock API key starting with sm_ |

## Tools (51)

- `list_mockups`: List the mockup templates in your own account with UUIDs, names, and thumbnails. Use returned UUIDs with render_mockup or get_mockup_details. To find a ready-made mockup from SudoMock's free library instead, use search_ready_made_mockups.
- `get_mockup_details`: Get full details of a mockup: smart object UUIDs, layer names, dimensions, positions, blend modes, and thumbnail URLs. A smart object whose contents hold smart objects or live text lists them in its own smart_objects and text_layers; fill any of them by UUID in the same render, like a top-level one. Set include_layers to true to also get data.layers: every layer of the template, nested the way Photoshop's Layers panel shows it and listed front-most first, each with uuid, name, kind, visible and children. An artboard has kind artboard; its own layers are listed right before it at the top level, not as its children. A smart object whose contents hold layers you can fill lists those layers as its children; copies of one smart object share their contents, which are listed under one copy. Layers hidden in the file are listed too, with visible false. Pass a layer's uuid in hidden_layers on render_mockup to leave that layer out of a render. Costs 0 credits.
- `update_mockup`: Rename a mockup template.
- `delete_mockup`: Permanently delete a mockup template. Cannot be undone.
- `render_mockup`: Render a PSD mockup with artwork, editable text, or both. Supports one or multiple smart objects and preserves the template's authored appearance. Name what to fill with any of these, alone or together: smart_object_uuid + artwork_url for one smart object, smart_objects entries ({uuid, asset or color}) for one or more, text_layers entries ({uuid, text or segments}), or text_layer_uuid + text for one text layer. Sent together they are combined into one render: the smart_object_uuid entry comes before the smart_objects entries, and the text_layer_uuid entry before the text_layers entries. Use text_fit when longer text should overflow, shrink to fit, or clip. A call that names nothing to render returns an error. To leave layers out of one render, pass their uuids in hidden_layers; get_mockup_details with include_layers lists every layer with its uuid, including the layers inside a smart object's contents. Hiding a group hides every layer inside it, a layer clipped to a hidden layer is hidden with it, as in Photoshop, and a layer hidden inside a smart object's contents is hidden in every copy of that smart object. hidden_layers works on its own. A layer cannot be hidden and edited in the same call, and a smart object that receives artwork cannot have layers inside it hidden. Returns the rendered image URL. Costs 1 credit. Use list_mockups and get_mockup_details to find target UUIDs.
- `remove_background`: Remove the background from any image and return a transparent-PNG cutout with clean, production-ready edges. The returned URL is valid for 7 days and can be used as artwork_url during that window. Costs 5 credits per image; credits are refunded automatically if processing fails.
- `check_seams`: Check whether a repeating pattern tile joins without a visible seam, before you render it with tile. Returns status: seamless, faint_seam or visible_seam. seams lists each side that does not join cleanly (left_right where the right edge meets the left, top_bottom where the bottom edge meets the top) with the pixel ranges along it. When status is visible_seam and fixable is true, suggest fix_seams; when fixable is false, unfixable_reason says why (transparent_edges or too_large). previous_fix holds your latest fix of the same image, if there is one, so it can be reused instead of fixed again. Synchronous. Costs 0 credits.
- `fix_seams`: Repair a repeating pattern tile so it repeats without a visible seam. Check the tile with check_seams first: a seamless tile needs no fix, and its previous_fix may already hold one. Always async: returns a job_id at once; read the result with get_job or wait_for_job. The finished job carries result_url, alternative_url (a second repaired version when one is available, otherwise null), result_status (the seam check of the result: seamless, faint_seam or visible_seam) and changes (edges when only the edges changed, whole_tile when the change reaches across the tile, rearranged when motifs were moved so none is cut). A tile with transparent edges, or one too large to fix, is refused without charge. A fix that fails with error_code TILE_NOT_FIXABLE carries error_details.reason (not_a_pattern_tile or no_clean_result), and its credits are refunded. Costs 60 credits; credits are refunded automatically if the fix fails.
- `list_fonts`: List fonts available for text layers: the shared system catalog plus any fonts you have uploaded. Filter by family name (search), by category (serif, sans-serif, display), or by scope ('all', 'system', or 'custom' for your uploads only); results are paginated (per_page up to 100). Use a font's uuid or postscript_name as the font of a text_layers entry when rendering with render_mockup. Costs 0 credits.
- `create_2d_mockup`: Create a reusable photo mockup from a public image URL. Returns the mockup ID and public render targets synchronously. Costs 25 credits. If the image is unsuitable, the 25 credits are refunded automatically. Set is_async=true to queue instead and receive a job_id to poll with get_job or wait_for_job. Use the dashboard for visual fine-tuning.
- `render_2d_surface`: Render artwork across a whole surface: an all-over print. Every printable product in the photo, and the main wall of a room photo, is a surface with its own surface_uuid, listed by get_2d_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Use the dashboard for visual fine-tuning.
- `render_2d_print_area`: Render artwork onto one saved print area -- a bounded zone somebody drew on the product, such as a chest logo. Read the print_area_id values from get_2d_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Use the dashboard for visual fine-tuning.
- `list_2d_mockups`: List your saved photo mockup templates (no PSD). Returns each mockup's mockup_id, name, status, thumbnail, dimensions, and print_areas. Use the mockup_id with get_2d_mockup to read the print-area and surface UUIDs a render needs. Costs 0 credits.
- `get_2d_mockup`: Get one photo mockup's full details: the saved print_areas[] somebody drew on it, and the surfaces[], one entry per printable product in the photo and one for the main wall of a room photo, each with a label. Pass a print_area_id to render_2d_print_area, or a surfaces[].surface_uuid to render_2d_surface. Costs 0 credits.
- `update_2d_print_areas`: Replace a photo mockup's print areas with up to 8 four-point quads and return the updated geometry. An area sent with print_area_id keeps that id; an area without one gets a new id. An empty list is accepted only for verified full surfaces. Costs 0 credits.
- `delete_2d_mockup`: Permanently delete a photo mockup template and all of its data. Cannot be undone. Costs 0 credits.
- `list_folders`: List the folders in your mockup library. PSD mockups and photo mockups share one tree, and every mockup sits in exactly one folder or at the top of the library. Each folder returns its uuid, name, parent_uuid (null at the top of the library) and how many folders, PSD mockups and photo mockups it holds directly. Pass a folder's uuid to list_mockups or list_photo_mockups as folder_uuid to see what is inside it. Costs 0 credits.
- `create_folder`: Create a folder in your mockup library, at the top of it or inside another folder. A name has to be unique among the folders beside it, whatever the capitalisation, so calling it twice never builds a second copy; the second call returns FOLDER_NAME_TAKEN. Returns the new folder's uuid for move_to_folder and for the folder_uuid filter on the mockup lists. Costs 0 credits.
- `move_to_folder`: Move any mix of PSD mockups, photo mockups and folders into one folder, or to the top of the library. Everything named in the call moves together or nothing does, so there is no half finished move to handle. Moving never changes a mockup's id, so renders, webhooks and integrations keep working against the ids they already hold. A folder moves with everything inside it. Costs 0 credits.
- `upload_psd`: Upload a Photoshop PSD/PSB file as a new mockup template. The PSD must have at least one Smart Object layer. Processing takes 5-30 seconds.
- `get_job`: Get the current status of any async render, video, upload, photo mockup, or seam fix job by its job_id. Returns status (queued|running|succeeded|failed), completed-result details and credits charged, or an error if failed. A seam fix job also reports stage (queued, fixing, finishing) while it runs. To block until done, use wait_for_job instead.
- `list_jobs`: List your async jobs, including PSD renders, videos, uploads, photo mockup creation and renders, and seam fixes, newest first. Use this when you do not already hold a job_id. Pass the returned next_cursor to fetch the next page.
- `wait_for_job`: Poll any async render, video, upload, photo mockup, or seam fix job until it succeeds or fails, then return the final result and credits charged. Blocks while polling.
- `render_video`: Create a short AI video from either a mockup with artwork or a public image URL. Supply exactly one input mode. Always async: returns a job_id immediately for get_job or wait_for_job. Credit cost depends on clip length, audio, and the automatically selected quality. Unsupported durations are rejected.
- `get_account`: Get your account info: the organization the API key belongs to, subscription plan, remaining credits, prepaid balance, usage stats, billing period, and API key details. The plan, credits and balance belong to that organization, so name it when you report them. An account is funded by a subscription allowance or by a prepaid balance, so read both: an account paying as it goes reports 0 credits and pays from its balance. Quote funding_summary rather than reading the credits fields alone.
- `create_webhook_endpoint`: Register a webhook endpoint that SudoMock calls when async jobs finish. The signing secret is returned IN FULL exactly once here -- store it to verify the HMAC carried in the X-SudoMock-Signature header (with X-SudoMock-Timestamp) on incoming deliveries. URL must be https and publicly routable.
- `list_webhook_endpoints`: List your registered webhook endpoints (id, url, subscribed event_types, enabled state). Secrets are NOT returned here -- only at creation and rotation.
- `update_webhook_endpoint`: Update a webhook endpoint in place: change its url, description, subscribed event_types, its event_naming pin, or enable/disable it (enabled:false pauses deliveries without losing the signing secret). All fields optional -- only the ones you pass are changed. The secret is NOT rotated or returned here.
- `delete_webhook_endpoint`: Permanently delete a webhook endpoint. SudoMock stops delivering to it. Cannot be undone.
- `rotate_webhook_secret`: Rotate the signing secret for a webhook endpoint. A new secret is returned IN FULL exactly once -- update your verifier with it. The old secret stops being valid.
- `test_webhook_endpoint`: Send a signed webhook.test event to verify endpoint reachability and signature handling. Returns a test job_id; check the result with list_webhook_deliveries.
- `list_webhook_deliveries`: List delivery attempts for a webhook endpoint (status, event_type, response code, timestamps). Use this to debug failed deliveries before replaying them.
- `replay_webhook_delivery`: Replay a single webhook delivery while preserving its event identity, e.g. after fixing your endpoint. Get delivery_id from list_webhook_deliveries.
- `replay_failed_webhook_deliveries`: Re-send every failed or dead delivery for a webhook endpoint in one call, e.g. after fixing your endpoint. Returns status and count: how many deliveries were queued to be sent again. To re-send a single delivery, use replay_webhook_delivery.
- `upload_local_file`: Upload a file from this machine and get back a URL for it. Use this when the file exists on disk and a tool needs a URL: pass the returned file_url as psd_file_url to upload_psd, or as artwork_url to any render tool. Set kind to "psd" for a .psd/.psb template or "artwork" for a .png/.jpg/.webp/.gif image. Costs 0 credits.
- `create_upload_url`: Get a place to send a file that only exists on your machine. Every other tool takes a URL, so a local file has to be uploaded first. Returns an upload_url to PUT the bytes to and the file_url they will have afterwards; pass that file_url as psd_file_url to upload_psd, or as artwork_url to any render tool. Set kind to "psd" for a .psd or .psb template, or "artwork" for a .png, .jpg, .webp or .gif image. The upload target is scoped to a single file and cannot be overwritten or read back through the same URL. When the file is on the machine running this server, upload_local_file uploads it in one step. Costs 0 credits.
- `search_ready_made_mockups`: Search SudoMock's free library of ready-made mockups. Nothing here needs a Photoshop file or a product photo of your own: 6,800+ ready-made mockups across 104 product types. A mockup is one view of a product scene (front, folded, flat lay, lifestyle, close-up) and a template is the set of views of that scene, 912 of them. Search by free text, category, product type or tag and you get templates back with every mockup they hold, each carrying the address to render from, so one call is enough to act on. Pass slug=<a hit's slug> to read one template with its long-form copy. Then send a mockup's source_url to create_photo_mockup: it becomes a reusable mockup on your account for 25 credits, and each render of it costs 5. This search itself reads only and costs 0 credits.
- `list_psd_mockups`: List the mockup templates in your own account with UUIDs, names, and thumbnails. Use returned UUIDs with render_mockup or get_mockup_details. To find a ready-made mockup from SudoMock's free library instead, use search_ready_made_mockups. Family-name spelling of list_mockups: one tool under two names, same arguments, same behavior. Either name works.
- `get_psd_mockup`: Get full details of a mockup: smart object UUIDs, layer names, dimensions, positions, blend modes, and thumbnail URLs. A smart object whose contents hold smart objects or live text lists them in its own smart_objects and text_layers; fill any of them by UUID in the same render, like a top-level one. Set include_layers to true to also get data.layers: every layer of the template, nested the way Photoshop's Layers panel shows it and listed front-most first, each with uuid, name, kind, visible and children. An artboard has kind artboard; its own layers are listed right before it at the top level, not as its children. A smart object whose contents hold layers you can fill lists those layers as its children; copies of one smart object share their contents, which are listed under one copy. Layers hidden in the file are listed too, with visible false. Pass a layer's uuid in hidden_layers on render_mockup to leave that layer out of a render. Costs 0 credits. Family-name spelling of get_mockup_details: one tool under two names, same arguments, same behavior. Either name works.
- `update_psd_mockup`: Rename a mockup template. Family-name spelling of update_mockup: one tool under two names, same arguments, same behavior. Either name works.
- `delete_psd_mockup`: Permanently delete a mockup template. Cannot be undone. Family-name spelling of delete_mockup: one tool under two names, same arguments, same behavior. Either name works.
- `render_psd_mockup`: Render a PSD mockup with artwork, editable text, or both. Supports one or multiple smart objects and preserves the template's authored appearance. Name what to fill with any of these, alone or together: smart_object_uuid + artwork_url for one smart object, smart_objects entries ({uuid, asset or color}) for one or more, text_layers entries ({uuid, text or segments}), or text_layer_uuid + text for one text layer. Sent together they are combined into one render: the smart_object_uuid entry comes before the smart_objects entries, and the text_layer_uuid entry before the text_layers entries. Use text_fit when longer text should overflow, shrink to fit, or clip. A call that names nothing to render returns an error. To leave layers out of one render, pass their uuids in hidden_layers; get_mockup_details with include_layers lists every layer with its uuid, including the layers inside a smart object's contents. Hiding a group hides every layer inside it, a layer clipped to a hidden layer is hidden with it, as in Photoshop, and a layer hidden inside a smart object's contents is hidden in every copy of that smart object. hidden_layers works on its own. A layer cannot be hidden and edited in the same call, and a smart object that receives artwork cannot have layers inside it hidden. Returns the rendered image URL. Costs 1 credit. Use list_mockups and get_mockup_details to find target UUIDs. Family-name spelling of render_mockup: one tool under two names, same arguments, same behavior. Either name works.
- `create_photo_mockup`: Create a reusable photo mockup from a public image URL. Returns the mockup ID and public render targets synchronously. Costs 25 credits. If the image is unsuitable, the 25 credits are refunded automatically. Set is_async=true to queue instead and receive a job_id to poll with get_job or wait_for_job. Use the dashboard for visual fine-tuning. Family-name spelling of create_2d_mockup: one tool under two names, same arguments, same behavior. Either name works.
- `list_photo_mockups`: List your saved photo mockup templates (no PSD). Returns each mockup's mockup_id, name, status, thumbnail, dimensions, and print_areas. Use the mockup_id with get_2d_mockup to read the print-area and surface UUIDs a render needs. Costs 0 credits. Family-name spelling of list_2d_mockups: one tool under two names, same arguments, same behavior. Either name works.
- `get_photo_mockup`: Get one photo mockup's full details: the saved print_areas[] somebody drew on it, and the surfaces[], one entry per printable product in the photo and one for the main wall of a room photo, each with a label. Pass a print_area_id to render_2d_print_area, or a surfaces[].surface_uuid to render_2d_surface. Costs 0 credits. Family-name spelling of get_2d_mockup: one tool under two names, same arguments, same behavior. Either name works.
- `update_photo_mockup_print_areas`: Replace a photo mockup's print areas with up to 8 four-point quads and return the updated geometry. An area sent with print_area_id keeps that id; an area without one gets a new id. An empty list is accepted only for verified full surfaces. Costs 0 credits. Family-name spelling of update_2d_print_areas: one tool under two names, same arguments, same behavior. Either name works.
- `delete_photo_mockup`: Permanently delete a photo mockup template and all of its data. Cannot be undone. Costs 0 credits. Family-name spelling of delete_2d_mockup: one tool under two names, same arguments, same behavior. Either name works.
- `get_2d_mockup_details`: Get one photo mockup's full details: the saved print_areas[] somebody drew on it, and the surfaces[], one entry per printable product in the photo and one for the main wall of a room photo, each with a label. Pass a print_area_id to render_2d_print_area, or a surfaces[].surface_uuid to render_2d_surface. Costs 0 credits. Second name of get_2d_mockup: one tool under two names, same arguments, same behavior. Either name works.
- `send_webhook_test_event`: Send a signed webhook.test event to verify endpoint reachability and signature handling. Returns a test job_id; check the result with list_webhook_deliveries. Second name of test_webhook_endpoint: one tool under two names, same arguments, same behavior. Either name works.
- `render_photo_mockup`: Render artwork onto a saved photo mockup. Name exactly one target: a print_area_uuid (a bounded zone somebody drew on the product, such as a chest logo; sized by fit or by width + height) or a surface_uuid (a whole printable product or the main wall of a room photo, for an all-over print; sized by coverage or by width + height). Read both from get_photo_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Family-name spelling of render_2d_surface and render_2d_print_area, which stay available and behave exactly as they did. Use the dashboard for visual fine-tuning.
- `render_2d_mockup`: Render artwork onto a saved photo mockup. Name exactly one target: a print_area_uuid (a bounded zone somebody drew on the product, such as a chest logo; sized by fit or by width + height) or a surface_uuid (a whole printable product or the main wall of a room photo, for an all-over print; sized by coverage or by width + height). Read both from get_2d_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Second name of render_photo_mockup: the same tool and behavior, with the mockup passed as mockup_uuid. Use the dashboard for visual fine-tuning.

## FAQ

### How do I authenticate with SudoMock?

You authenticate using your SUDOMOCK_API_KEY provided as an environment variable in your MCP client.

### Can I use this server with Claude or Cursor?

Yes, the server is designed to work with Claude, Cursor, Windsurf, and VS Code.

### Does the server support remote HTTP/OAuth transport?

No, currently only a local stdio server is available.

### How long do background removal URLs last?

The transparent-PNG cutout URLs provided by the background removal tool are available for 7 days.
