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 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.
|
|
|
|
|
|
|
|
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, family and tag are 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.
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: Store Screenshot Generator MCP
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? |
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/",
)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
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.
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 |
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.
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.
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 size means hi-res, which hard-fails with feature-not-available
on any plan without it. This server always sends size explicitly, capped by
MOCKUUUPS_MAX_SIZE (default 1000, the Trial ceiling). Raise it when the
account has the hires feature.
On plans with cdn-temporary, delivery links expire after ~24 hours.
Download anything worth keeping. account_status reports this.
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.
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 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.
If this server saves you time, you can buy me a coffee.
Released under the MIT License.
[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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| plan | Yes | |
| status | Yes | |
| account | Yes | |
| summary | Yes | |
| features | Yes | |
| credits_left | Yes | |
| credits_used | Yes | |
| max_render_size | Yes | |
| cdn_links_expire | Yes | |
| hi_res_available | Yes | |
| uploads_configured | Yes | |
| screenshots_available | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by disclosing credit costs (1 for a render, 2 for a screenshot) and feature-availability semantics that an agent cannot infer from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the two core questions the tool answers, followed by detail. The rhetorical 'How many credits are left, and what can this plan do?' framing is slightly verbose but effectively communicates scope in a short block.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value structure need not be repeated, and the description covers credits, feature gating, and cost implications. Complete for a zero-parameter status tool, though it omits any mention of how often status changes or caching.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to document and the baseline is 4. The credit-cost detail, while not a parameter, further informs invocation decisions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Reports the credit balance plus which features are actually available') and enumerates the concrete facts returned (hi-res, screenshots, CDN expiry). This is clearly distinguishable from the sibling list/search/create/render tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear when-to-use trigger: 'Worth checking before a batch,' reinforced by the per-operation credit costs. It does not name an alternative tool or an exclusion, but the intent is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| image_url | No | ||
| mockup_ids | Yes | ||
| image_base64 | No | ||
| wait_seconds | No | ||
| screenshot_url | No |
| Name | Required | Description |
|---|---|---|
| failed | Yes | |
| pending | Yes | |
| renders | Yes | |
| summary | Yes | |
| requested | Yes | |
| succeeded | Yes | |
| credits_spent | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing credit costs per render and per screenshot, the concurrent execution of multiple mockup_ids, the base64 staging-to-short-lived-URL behavior, and the pending/render_id outcome when the wait budget is exceeded. This is exactly the operational context the annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then organized into a source-selection block and a cost/behavior block; every sentence carries information. It is somewhat long for a tool description, though the length is earned by the genuine complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter mutation tool with an output schema present, the description covers input selection rules, cost model, concurrency, base64 constraints, and the asynchronous pending path. Nothing an agent needs before invoking it correctly is missing, aside from the minor `size` omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must supply parameter meaning; it thoroughly explains the three mutually exclusive source parameters and mockup_ids, plus implies wait_seconds via the 'wait budget' remark. However, the `size` parameter is never mentioned, leaving one of six parameters undocumented anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb, resource, and scope: 'Put one design into one or more mockups and render them.' Combined with the sibling set (search_mockups, get_renders, account_status), the agent can immediately tell this is the render-creation tool rather than a search or polling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly bounds the input choice ('Give exactly one source') and names the conditions selecting each option (websites vs. any public image vs. local-only files). It also routes the agent to account_status before large batches and to get_renders for pending results, covering when-not and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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.
| Name | Required | Description | Default |
|---|---|---|---|
| render_ids | Yes | ||
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
| failed | Yes | |
| pending | Yes | |
| renders | Yes | |
| summary | Yes | |
| requested | Yes | |
| succeeded | Yes | |
| credits_spent | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: long-polling until renders settle or a budget is exhausted. It omits auth requirements, rate limits, and failure behavior for unknown render_ids, keeping it at a solid 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core polling constraint, then the wait_seconds trade-off. No filler; every clause carries meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value description is unnecessary, and the description covers purpose, origin, and polling behavior. Minor gaps remain around behavior with invalid or unknown render_ids and whether results reflect all requested IDs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fully explains wait_seconds semantics (default 0 = check once; positive = long-poll until settle or budget expiry), which is the non-obvious parameter. render_ids is left implicit, which the tool name and origin context mostly cover.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (poll/get renders) and ties it explicitly to create_mockups as the producer of the pending renders. An agent can distinguish it from siblings like create_mockups or search_mockups without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the trigger condition clearly (renders returned as pending from create_mockups) and the choice between wait_seconds > 0 for long-polling versus 0 for a single immediate check. It does not spell out when not to use it (e.g., fetching already-settled renders), so it falls just short of explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| kind | No | ||
| limit | No | ||
| query | No | ||
| family | No |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| types | No | |
| mockups | Yes | |
| summary | Yes | |
| families | No | |
| catalog_size | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context: the scale of the corpus (~5300 scenes), that scenes shot together share a tag, and that results feed create_mockups. It does not disclose result volume or how `limit`/pagination behaves, keeping it below 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose with a question, then elaborates per-parameter in scannable paragraphs, ending with the workflow handoff. Slightly verbose in places, but every section adds usable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and the description covers the search facets and downstream workflow well. The only material gap for correct invocation is the unexplained `limit` default and result-cap behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry the load, and it meaningfully documents query (understands everyday words and exact slugs like "ipad-air"), family (with example values), kind, and especially tag semantics. It omits any explanation of the `limit` parameter (default 12), so 4 rather than 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (searches) and resource (~5300 Mockuuups scenes) along with the facets searched (device, scene, style). This clearly separates it from create_mockups and get_renders without needing to open a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains how to combine parameters (query with family or kind) and calls out that `tag` is the strongest lever for cross-device consistency, plus routing advice to pass the returned id to create_mockups. It lacks an explicit when-not-to-use or a named alternative tool for other cases, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.7account_statuscreate_mockupsget_renderssearch_mockupsScored 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.
Create app-store screenshots, social graphics, promo videos, and animated device mockups.
Design mockups, device frames and launch graphics live in your open Brayer studio tab.
Turn product photos or PSD templates into photorealistic mockups: place artwork, edit text, render.
Generate images, videos and PDFs from templates. Manage templates, folders, uploads and fonts.
