# design-canvas-mcp

MCP server for [Design Canvas](https://designcanvas.app) — 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. This MCP server lets AI agents (Claude Code, Cursor) add routes, 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

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

### Cursor

Add to `.cursor/mcp.json`:

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

### Global install (alternative)

```bash
npm install -g design-canvas-mcp
```

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

## Tools

| 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` |
| `capture_canvas` | Capture 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
- "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.

## License

MIT