Connect DesignJS to Claude Code

Two ways to register DesignJS as an MCP server in Claude Code — automatic via designjs init, or manual via claude mcp add — plus verification steps.

DesignJS exposes a Model Context Protocol (MCP) server that Claude Code connects to over stdio. Once connected, Claude can read your canvas (component tree, HTML, CSS, screenshots) and write to it (insert components, update styles, delete nodes) — all without leaving the conversation. This page walks you through both the automatic and manual setup paths.

Prerequisites

Before connecting, make sure DesignJS is running:

pnpm dev

The canvas opens at http://localhost:3000 and the WebSocket bridge starts listening on 127.0.0.1:29170. The bridge status indicator in the top-right corner of the editor turns green when an MCP server process connects.

Method 1 — Scaffold a fresh project

The create-designjs scaffolder (published on npm) drops .mcp.json, CLAUDE.md, and a README.md into a new directory in one command:

npm create designjs@latest my-app
cd my-app

Then launch Claude Code from inside my-app (not its parent — Claude Code reads .mcp.json from the cwd it was launched in, and launching from the parent won’t pick up the project config):

claude

The CLAUDE.md that ships with the template includes explicit guidance nudging the agent toward the designjs.* tools and away from other design MCPs (Pencil, Paper, Figma) that might be configured globally.

create-designjs refuses to scaffold into a non-empty directory. For existing projects, use Method 2.

Method 2 — Manual configuration (existing projects)

Write .mcp.json by hand in the project root:

{
  "mcpServers": {
    "designjs": {
      "command": "npx",
      "args": ["-y", "@designjs/mcp-server"]
    }
  }
}

Or register DesignJS at user scope so it’s available across every Claude Code project, not just this one:

claude mcp add designjs --scope user -- npx -y @designjs/mcp-server

This writes into your Claude Code user config (~/.claude.json) instead of the project. Use --scope project if you want the current project only.

Verifying the connection

1. Start a Claude Code session

   Open Claude Code in your project directory where .mcp.json is located.

2. Run /mcp

   Type /mcp in the Claude Code chat. It should list designjs along with all available tools.

   You should see 20+ tools including ping, get_tree, get_html, get_css, get_screenshot, get_selection, add_components, update_styles, and delete_nodes.

3. Test with ping

   Ask Claude: “Call the designjs ping tool.” If the canvas is running and the bridge is connected, the response will include { pong: true, at: <timestamp> }. The bridge status dot in the editor will also turn green.

Troubleshooting

designjs not listed in /mcp at all

You launched Claude Code from the wrong directory. Claude Code reads .mcp.json from the cwd it was started in — cd into the project directory first, then claude. Also: if Claude Code is showing a trust-this-project prompt, accept it — project MCP servers stay disabled until you do.

designjs · ◯ connecting… never turns green

First launch downloads @designjs/mcp-server via npx -y — 10–30 seconds on cold cache, then instant. If it’s stuck past a minute, run npx -y @designjs/mcp-server </dev/null standalone to confirm the install works.

designjs · ✘ failed

The MCP server started but couldn’t reach the canvas bridge on 127.0.0.1:29170. Start the canvas: pnpm dev in the DesignJS repo. Check the topbar bridge dot — grey means the canvas isn’t running.

The agent used Pencil / Paper / Figma instead of DesignJS

You have competing design MCPs registered globally in ~/.claude.json. The CLAUDE.md that create-designjs drops tells the agent to prefer DesignJS — but you can reinforce it in the prompt itself (“use designjs, not pencil”) or remove the competing entries from your user config.

Stale 'opencanvas' entry shows as failed

Pre-rebrand entries in ~/.claude.json’s mcpServers try to reconnect on every launch. Open the file and delete the "opencanvas" key from the mcpServers object; restart Claude Code.

Tool call hangs with no response

The MCP server started but the bridge dropped. Restart the canvas (pnpm dev), then start a fresh Claude Code session — the server reconnects automatically.

If you have multiple MCP servers registered under the same designjs name (e.g., one project-scope and one user-scope), the last one registered wins. Run /mcp to audit.