mockupflo-mcp

mockupflo-mcp

The private / local connector between AI agents and the Mockupflo editor. Claude Code, Cursor, Codex, VS Code, Claude Desktop and other MCP clients run it on your own machine. The agent can then:

• read your open project;
• edit it while you watch (devices, screenshots, camera, backgrounds, animation, templates);
• look at snapshots of the result;
• export files.

Everything stays on your computer.

AI client ──stdio──▶ npx mockupflo-mcp ◀──ws://127.0.0.1:7331── editor tab (mockupflo.com/app)

Most people don't need this package. The default way to connect is the hosted endpoint, https://mockupflo.com/api/mcp plus an access token, with nothing to install. See the setup guide at mockupflo.com/mcp. Use this package if you'd rather not have anything pass through Mockupflo's servers.

Both modes need a Mockupflo Pro account.

Setup

The full guide, with a snippet for every client and troubleshooting, is at mockupflo.com/mcp#local. In short:

1. Check what you need. A Mockupflo Pro account, Node.js 18 or later (node -v), and Chrome, Edge or Firefox. Safari can't reach your own computer from a website, so use the hosted connection there.

2. Turn on local mode. In the editor, open the menu → Preferences → AI agents and switch on Private / local mode. The status reads "Waiting for mockupflo-mcp on 127.0.0.1:7331" until the connector runs.

3. Add the connector to your AI client. npx fetches it the first time the client starts it.

   Claude Code

   claude mcp add mockupflo-local -- npx -y mockupflo-mcp

   On Windows outside WSL, use claude mcp add mockupflo-local -- cmd /c npx -y mockupflo-mcp.

   Cursor (~/.cursor/mcp.json), Claude Desktop (Settings → Developer → Edit Config), Windsurf (~/.codeium/windsurf/mcp_config.json), Gemini CLI (~/.gemini/settings.json)

   { "mcpServers": { "mockupflo-local": { "command": "npx", "args": ["-y", "mockupflo-mcp"] } } }

   VS Code (.vscode/mcp.json)

   { "servers": { "mockupflo-local": { "type": "stdio", "command": "npx", "args": ["-y", "mockupflo-mcp"] } } }

   Codex (~/.codex/config.toml, or run codex mcp add mockupflo-local -- npx -y mockupflo-mcp)

   [mcp_servers.mockupflo-local]
   command = "npx"
   args = ["-y", "mockupflo-mcp"]

4. Restart the client and check the tab. The editor's status turns to "Connected to mockupflo-mcp" and a robot icon appears in its top bar. The first time, Chrome or Edge may ask whether mockupflo.com may access devices on your local network; allow it. To check the connector on its own, run npx -y mockupflo-mcp in a terminal. It should print ready (bridge port 7331, …) and hub listening on 127.0.0.1:7331 (or joined the hub when your AI client already runs one), and the editor should connect to it. Press Ctrl+C to stop it.

5. Prompt. A local extra: the agent reads screenshots straight from paths on your disk and can save exports into a folder.

Use the server name mockupflo-local so it doesn't clash with the hosted connection (mockupflo) if you configure both.

Troubleshooting

• Stuck on "Waiting for mockupflo-mcp": the client hasn't started it. Check that it's listed and enabled (claude mcp list, Cursor Settings → MCP), restart the client, and run npx -y mockupflo-mcp in a terminal to see any error.
• Port busy: set a free port in the client config ("env": { "MOCKUPFLO_MCP_PORT": "7332" }, or claude mcp add mockupflo-local -e MOCKUPFLO_MCP_PORT=7332 -- npx -y mockupflo-mcp) and the same port in Preferences → AI agents.
• No connection and no permission prompt: open the site settings for mockupflo.com (the icon left of the address), allow local network access, and reload the editor.
• npx not found: install Node.js 18+ and restart the client so it picks up the new PATH.

From a checkout of the Mockupflo repo

Run npm run mcp:install once, then point the client at node <repo>/mcp/server.mjs. The repo ships .mcp.json (Claude Code), .cursor/mcp.json and .vscode/mcp.json configured this way. Launch it with node directly rather than npm run, because npm prints to stdout and stdout is the MCP channel.

Configuration

Variable	Default
MOCKUPFLO_MCP_PORT	7331	Bridge port. If you change it, set the same port in the editor's preferences.
MOCKUPFLO_URL	https://mockupflo.com/app	What open_editor opens, e.g. http://localhost:3000/app for a local dev server.
MOCKUPFLO_ALLOWED_ORIGINS		Extra comma-separated browser origins allowed to connect as an editor. Loopback origins and mockupflo.com are always allowed.

Tools

The tools are the same as on the hosted endpoint, with two local extras:

• set_media reads file paths straight from disk.
• export can write to a path (saveTo).

Area	Tools
Tabs	list_editors, select_editor, open_editor
Reading	get_state, get_shot, get_catalog, list_templates, snapshot (returns an image), get_changes (long-poll for real-time changes)
Look	set_look, select_device, set_media
Timeline	add_shot, update_shot, select_shot, duplicate_shot, move_shot, split_shot, delete_shots
Animation	set_keyframes, delete_keyframes, apply_animation_preset, smart_animate
Project	apply_template, set_project, reset_project, history, playback, export

Several tabs: with more than one editor tab open, calls fail with a list of the tabs until the agent asks you which one to use and calls select_editor. The chosen tab shows a note.

Several clients: each client runs its own copy of the connector. The first copy binds the port and becomes the hub; later copies relay through it, so the browser dials one address. If the hub exits, a peer takes over and the tab reconnects by itself.

Security

• The hub listens on 127.0.0.1 only and refuses non-loopback Host headers, which guards against DNS rebinding.
• /editor accepts only allowed browser origins, so no other website can pose as the editor.
• /agent (the peer endpoint) refuses any request that carries an Origin header. Browsers always send one, so a web page can never drive your editor through the hub.
• The editor connects only when you turn local mode on, and only on a Pro account.

Browsers

On https://mockupflo.com:

• Chrome and Edge treat loopback as a secure context, but newer versions ask once for permission to reach local devices.
• Firefox connects as well.
• Safari blocks ws://127.0.0.1 from an HTTPS page, so use the hosted endpoint there.

Playback previews advance only while the tab is visible. Edits, snapshots and exports work from a background tab.

Development

• npm test (or npm run mcp:test from the repo root) runs test/smoke.mjs. It covers two servers, fake editor tabs, the origin rules, relayed requests, tab selection, change events and hub failover.
• The editor side lives in src/mcp/ of the Mockupflo repo:
  • localBridge.ts and localProtocol.ts: this connection.
  • handlers.ts: the operations, shared with the hosted mode.
• Keep tools in step with the hosted endpoint in src/server/mcp/tools.ts. Bump PROTOCOL_VERSION (in lib/hub.mjs and localProtocol.ts) only when the frame format changes.
• To publish, run npm publish from this folder. The package name is mockupflo-mcp, and server.mjs is the bin.