mcp-mockuuups
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-mockuuups search for an iPad mockup and render my homepage screenshot on it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-mockuuups
MCP server for Mockuuups Studio — search ~5,300 device and print mockups, then render a screenshot or your own image into them.
One design — the WTDIB Berlin city guide — rendered into four mockups from a single photoshoot, so the room stays put while the device changes. Two tool calls, no image hosting anywhere.
|
|
|
|
|
|
|
|
Why this exists
Mockuuups ship their own hosted MCP server
at https://mcp.mockuuups.studio/mcp. It exposes a single generate_mockup tool
that needs a mockup id you already know and an image you have already hosted
somewhere public.
This server wraps the underlying REST API instead, and closes the two gaps that made the hosted one awkward in practice:
You can search. The upstream catalog endpoint accepts no search parameters at all —
q,type,familyandtagare silently ignored and every request returns the same unfiltered page. The whole catalog is fetched once and searched locally, so "a tablet on a desk" or "poster" actually finds something.You can upload. Mockuuups renders from a URL only. Hand this server raw image bytes and it stages them under a short-lived unguessable link for the renderer to fetch, so a local design needs no bucket, no CDN and no hosting.
Rendering an image you hold locally
Mockuuups renders from a URL only. Pass image_base64 and this server stages the
bytes under a short-lived unguessable link, lets the renderer fetch it, and lets
it expire — no bucket, no CDN, no hosting account.

The iPad render above, uploaded from disk and rendered into a framed A3 poster.
Related MCP server: SudoMock
Tools
Tool | What it answers |
| Which mockup should I use? Free-text search over the whole catalog, with device-word aliases ("tablet", "poster", "laptop") and family/type/tag filters. |
| Put this design into these mockups. Takes a |
| Did those renders finish? Polls anything that outran the inline wait budget. |
| How many credits are left, and what can this plan actually do? |
Rendering one design across devices
Scenes shot together share a tag, so the way to get a consistent look across devices is to search one, then filter by its tag:
search_mockups(query="ipad", tag="update-august-2024-meeting-room")
create_mockups(
mockup_ids=["Zkn1GMTfiAFX5ZOn", "Zkn2DsTfiAFX5ZPD", "Zkn15MTfiAFX5ZO_"],
screenshot_url="https://wtdib.cdit-works.de/",
)Requirements
Python 3.12 or newer
FastMCP 4 (
fastmcp>=4.0.10,<5.0.0, installed as a dependency)A Mockuuups Studio account with a developer API key from mockuuups.studio/developers
Install and run
The package is not on PyPI; run it from a checkout.
git clone https://github.com/CaseyRo/mcp-mockuuups && cd mcp-mockuuups
uv sync
MOCKUUUPS_API_KEY=... uv run mcp-mockuuups # stdio
TRANSPORT=http MCP_API_KEY=change-me MOCKUUUPS_API_KEY=... uv run mcp-mockuuups # streamable HTTP on /mcpWith Docker, the image builds from source:
cp .env.example .env # fill in the keys
docker compose --env-file .env up -d --buildcompose.yaml publishes the server on host port 8013 and has no volumes on purpose: staged uploads live in memory. The container exposes /health.
Configuration
Every setting is an environment variable; .env.example lists the common ones.
Variable | Default | Purpose |
| none | Mockuuups Studio developer key |
| empty | This server's public origin. Needed only for |
|
| Largest render size sent upstream. Raise it when the plan has the |
|
| How long a staged upload stays fetchable |
|
| Size cap for one uploaded image (12 MiB) |
|
| How long the fetched catalog is cached |
|
| Inline wait for renders before handing back |
|
|
|
|
| Bind address |
|
| Bind port |
| none | Bearer token for the MCP endpoint. Required when |
Authentication
Over HTTP, MCP requests must carry Authorization: Bearer <MCP_API_KEY>. The only unauthenticated routes are /health, /healthz and the staged-upload route GET /i/{token}.{ext}, which the Mockuuups renderer has to reach. That route is protected by a 256-bit random token, a short TTL, a size cap, and a check that only real image bytes are served.
Slow renders
create_mockups dispatches every render concurrently and waits up to RENDER_WAIT_SECONDS. Anything still running comes back as pending with a render_id; the CDN links are already allocated. Pass those ids to get_renders (optionally with wait_seconds to long-poll) until they settle. Failures raise a tool error.
Plan limits worth knowing
The API bills in credits: one render = 1 credit, +1 for a website screenshot, +1 for hi-res. Only successful renders are charged.
Two behaviours will bite you if you don't know them:
Omitting
sizemeans hi-res, which hard-fails withfeature-not-availableon any plan without it. This server always sendssizeexplicitly, capped byMOCKUUUPS_MAX_SIZE(default 1000, the Trial ceiling). Raise it when the account has thehiresfeature.On plans with
cdn-temporary, delivery links expire after ~24 hours. Download anything worth keeping.account_statusreports this.
Usage telemetry
A small middleware (usage.py) writes one JSON line per tool call to stderr with the server name, tool name, duration, outcome and protocol version. It never logs arguments or results.
Development
uv sync
uv run pytestTests need no network: the catalog, upload store and every tool are covered with fakes. CI (.github/workflows/ci.yml) runs them as the test check on every pull request. main is protected and changes land through pull requests.
Releases
Releases are tag-only. After a merge to main, the release workflow tests the code and pushes the next v* patch tag; nothing is committed back to main. Do not bump version in pyproject.toml by hand. Deployments build the Docker image from source.
Support
If this server saves you time, you can buy me a coffee.
License
Released under the MIT License.
Available Tools
4 toolsaccount_statusAccount statusARead-onlyIdempotent
[mockuuups] How many credits are left, and what can this plan do? Reports the credit balance plus which features are actually available — hi-res, website screenshots, and whether CDN links expire. Worth checking before a batch: a plain render costs 1 credit and a screenshot costs 2.
Inputs: no named parameters. Returns: plan, status, account, summary, +8 more
create_mockupsCreate mockupsA
[mockuuups] Put one design into one or more mockups and render them.
Give exactly one source:
screenshot_url— Mockuuups screenshots the live page itself. Best for websites; costs one extra credit per render.image_url— any publicly reachable image.image_base64— raw image bytes for a design that only exists locally. Mockuuups can only render from a URL, so the image is staged on this server under a short-lived unguessable link for the render to fetch.
Pass several mockup_ids to render the same design across devices in one
call; they run concurrently. Renders that outrun the wait budget come back
as pending with a render_id for get_renders — the CDN links are already
valid and will fill in once the render lands.
Each render costs a credit, +1 for a screenshot, so check account_status before a large batch.
Inputs: mockup_ids (required), size, image_url, image_base64, +2 more. Returns: failed, pending, renders, summary, +3 more
get_rendersGet rendersARead-onlyIdempotent
[mockuuups] Did those renders finish? Poll renders create_mockups
returned as pending. With wait_seconds it long-polls until they settle or
the budget runs out; with 0 it checks once and returns immediately.
Inputs: render_ids (required), wait_seconds. Returns: failed, pending, renders, summary, +3 more
search_mockupsSearch mockupsARead-onlyIdempotent
[mockuuups] Which mockup should I use? Searches all ~5300 Mockuuups scenes by device, scene and style.
query is free text and understands everyday device words — "tablet",
"laptop", "poster", "smartwatch" — as well as exact placement slugs like
"ipad-air". Combine it with family (iPhone, iPad, MacBook, TV, Paper,
Apple Watch, Samsung, Google, iMac, ...) or kind to narrow.
tag is the strongest way to get one consistent look across several
devices: scenes shot together share a tag, so filtering by a tag returned
on a mockup you like gives you the rest of that shoot. Pass the returned
id to create_mockups.
Inputs: tag, kind, limit, query, +1 more. Returns: count, types, mockups, summary, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a clearly distinct stage of the workflow: account_status (billing/plan), search_mockups (discovery), create_mockups (rendering), get_renders (polling async results). No two tools overlap in purpose, and descriptions reinforce the boundaries.
Three of four tools use a consistent verb_noun pattern (search_mockups, create_mockups, get_renders). account_status breaks the pattern with a noun_noun form, but it is still readable and unambiguous.
Four tools cleanly cover the mockup rendering lifecycle without redundancy or padding. The count is well matched to the narrow purpose of the server.
The core loop (check credits, search scenes, render, poll results) is fully covered. Minor gaps exist, such as no way to list prior renders or browse available families/tags independently, but agents can work around these via search.
Maintenance
Related MCP Connectors
Print, vector and mockup APIs with free MCP discovery and x402 requests from 0.02 USDC.
Render your own PSD mockups: an exact Photoshop match, print-resolution output, OAuth.
Design mockups, device frames and launch graphics live in your open Brayer studio tab.
Create app-store screenshots, social graphics, AI and device-only videos.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to generate product mockups by integrating with the Dynamic Mockups API. Supports browsing mockup catalogs, creating single or batch renders with design assets, and managing PSD templates.1344 npm1MIT
- AlicenseNot gradedqualityBmaintenanceProduct mockup rendering API for e-commerce and print-on-demand. Upload Photoshop PSD templates, render photorealistic mockups by placing your designs onto smart object layers. 9 tools including AI-powered render (no PSD needed), template management, and account info. Supports remote HTTP (OAuth) and local stdio (npx) transports.1,116 npmMIT
ultramock-mcpDeprecated
AlicenseAqualityDmaintenanceEnables AI agents to create and configure product mockups on ultramock.io using your own logged-in subscription.111MIT- AlicenseNot gradedqualityBmaintenanceEnables rendering App Store and Google Play screenshots from AppScreen layout JSON and referenced image files, and polling render jobs for status and signed download links.65 npmMIT



