# mockupflo-mcp

> Private / local MCP connector between AI agents (Claude Code, Cursor, Codex, …) and the Mockupflo editor open in your browser

Latest version **0.1.1** (published 2026-09-23) · FSL-1.1-MIT license · 0 weekly downloads

## Install

```sh
npm install mockupflo-mcp
pnpm add mockupflo-mcp
yarn add mockupflo-mcp
bun add mockupflo-mcp
```

Provides the command `mockupflo-mcp`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2026-09-23 |
| First published | 2026-09-23 |
| Weekly downloads | 0 |
| License | FSL-1.1-MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=18.17 |
| Dependencies | 3 |
| Unpacked size | 65.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | supratikrulz |
| Keywords | mcp, model-context-protocol, mockupflo, mockup, claude, cursor, codex |

## Links

- npm: https://www.npmjs.com/package/mockupflo-mcp
- Homepage: https://mockupflo.com/mcp
- npm.io page: https://npm.io/package/mockupflo-mcp

## Dependencies (3)

- [ws](https://npm.io/package/ws.md) ^8.21.3
- [zod](https://npm.io/package/zod.md) ^4.6.5
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.30.0

## Alternatives

- [pagerjs](https://npm.io/package/pagerjs.md) — 60 weekly downloads
- [whistle.savefor-mock](https://npm.io/package/whistle.savefor-mock.md) — 4 weekly downloads
- [visual-companion](https://npm.io/package/visual-companion.md) — 0 weekly downloads
- [@vhictor/amockgen](https://npm.io/package/@vhictor/amockgen.md) — 0 weekly downloads
- [wallpaper-engine-web-dev-kit](https://npm.io/package/wallpaper-engine-web-dev-kit.md) — 0 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2026-09-23
- 0.1.0 — 2026-09-23

## README

# mockupflo-mcp

The private / local connector between AI agents and the [Mockupflo](https://mockupflo.com) 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](https://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](https://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**

   ```bash
   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`)

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

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

   ```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`)

   ```toml
   [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.

---
_Source: https://npm.io/package/mockupflo-mcp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._