design-canvas-mcp

MCP server for Design Canvas — control the infinite canvas from AI coding agents.

Design Canvas is a native Mac app that shows all your web app's routes on an infinite canvas with live browser views — alongside markdown docs and reference images. This MCP server lets AI agents (Claude Code, Cursor) add routes, drop in spec/plan markdown, attach reference imagery, capture screenshots, and manage what's displayed.

Prerequisites

• Design Canvas Mac app must be running on your machine
• The app must be connected to a running dev server (e.g., localhost:3000)
• Node.js 20+

Installation

Claude Code

claude mcp add design-canvas -s user -- npx -y design-canvas-mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "design-canvas": {
      "command": "npx",
      "args": ["-y", "design-canvas-mcp"]
    }
  }
}

Global install (alternative)

npm install -g design-canvas-mcp

Then configure with command: "design-canvas-mcp" instead of the npx variant.

Tools

Eleven tools across three frame types, plus a shared screenshot tool.

Routes (live dev-server pages)

| Tool | Description | Key Parameters | |------|-------------|----------------| | list_routes | List all routes on the canvas with IDs, paths, dimensions, positions | — | | add_route | Add a route to the canvas from the connected dev server | path (required), width (1280/768/375) | | remove_route | Remove a route frame by ID or path | id (preferred) or path | | update_route | Pin a navigated URL as the route's new path (mutates the saved route) | id (required), newPath (must start with /) |

Markdown documents

| Tool | Description | Key Parameters | |------|-------------|----------------| | list_documents | List all markdown frames on the canvas | — | | add_document | Add a .md file as a dark-themed knowledge card frame | filePath (absolute, required) | | remove_document | Remove a markdown frame by ID | id (required) |

Images

| Tool | Description | Key Parameters | |------|-------------|----------------| | list_images | List all image frames on the canvas | — | | add_image | Add a PNG/JPG/GIF/SVG/HEIC reference image as a frame | filePath (absolute, required) | | remove_image | Remove an image frame by ID | id (required) |

Screenshots

| Tool | Description | Key Parameters | |------|-------------|----------------| | capture_canvas | Capture fresh screenshots of routes and return as images | ids (optional), limit (default: 3) |

Example prompts

• "Show me all routes on the canvas" → list_routes
• "Add /dashboard at desktop and mobile" → add_route at 1280 + 375
• "Drop the spec at docs/spec.md onto the canvas next to the dashboard" → add_document
• "Pin the Linear inspiration screenshot from ~/Pictures/linear.png" → add_image
• "Capture the canvas so you can see my app" → capture_canvas
• "Remove the mobile version of /dashboard" → list_routes then remove_route by ID

How it works

The MCP server communicates with the Design Canvas Mac app via a local HTTP API on localhost:7420. The server is an adapter layer — it translates between the HTTP API and MCP's content block format.

Claude Code / Cursor
    → spawns design-canvas-mcp (stdio)
        → HTTP requests to localhost:7420
            → Design Canvas Mac app responds

Screenshots are captured by the Mac app's WebKit rendering engine, resized to 1200px width, and returned as base64 JPEG images.

Troubleshooting

"Design Canvas is not running" The Mac app isn't open or isn't listening on port 7420. Open Design Canvas and make sure it shows the canvas view.

Routes show but pages are blank The dev server isn't running. Start your dev server (e.g., npm run dev) and make sure Design Canvas is connected to it.

Screenshots are from WebKit, not Chrome Design Canvas uses WebKit (Safari's engine) for rendering. For pixel-perfect Chromium verification, use Playwright. The MCP screenshots are for quick layout checks, not cross-browser QA.

MCP fails to connect after rotating workspaces or cleaning npm cache If claude mcp list shows design-canvas — ✗ Failed to connect, your config likely has a stale absolute path. Run:

npx -y design-canvas-mcp repair

This rewrites stale entries in ~/.claude.json and ~/.cursor/mcp.json to the safe npx -y design-canvas-mcp@latest form. Restart your agent to pick up the change. Versions before 0.4.0 wrote absolute paths by default; 0.4.0+ writes the npx form, which is stable across workspace rotation and cache GC.

--absolute install flag design-canvas-mcp install --absolute writes an absolute Node + dist path instead of the npx invocation. Only use this if your agent (Claude Desktop, Cursor.app) can't find npx on PATH. Trade-off: absolute paths can rot — prefer the default unless you know you need it.

Support

• Email: [email protected]
• Telegram: @charlieellington

License

MIT