chili3d-mcp

An MCP server that lets an AI drive Chili3D — the browser CAD app — in a real browser. The page owns the document and every modeling tool; this package is the local half that connects an MCP client to it.

Claude Code / Codex / WorkBuddy / Cursor
        │ MCP (stdio)
        ▼
   chili3d-mcp  ── WebSocket ──►  https://chili3d.com/?bridge=17373
        │                           the page's own tool registry
        └── CLI (fallback for agents that only have a shell)

The tools are not reimplemented here. chili3d-mcp forwards calls to the same registry the app's in-app assistant runs, so run_program, load_skill, selections, viewport clicks and screenshots behave identically whether the work was started from the app or from an external agent.

Requirements

• Node.js 20+.

• A Chili3D build that includes the ?bridge= connector. https://chili3d.com ships it once deployed; for a local build use --app-url http://localhost:8080.

Related MCP server: ps3d

Install

The server is npx -y @chili3d/mcp mcp. init writes the entry note each agent needs.

Claude Code

claude mcp add chili3d -- npx -y @chili3d/mcp mcp
npx -y @chili3d/mcp init --agent claude --user     # ~/.claude/skills/chili3d/SKILL.md

Codex

npx -y @chili3d/mcp init --agent codex              # AGENTS.md block

Then add to ~/.codex/config.toml:

[mcp_servers.chili3d]
command = "npx"
args = ["-y", "@chili3d/mcp", "mcp"]

WorkBuddy

npx -y @chili3d/mcp init --agent workbuddy --user --write

Or add this to ~/.workbuddy/mcp.json yourself:

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

Then trust the server: sidebar → Plugins → MCP Servers.

Cursor

npx -y @chili3d/mcp init --agent cursor             # .cursor/rules/chili3d.mdc

Add the same mcpServers entry to .cursor/mcp.json.

Any agent with a shell

The CLI exposes the same tools:

npx -y @chili3d/mcp start --app-url http://localhost:8080
npx -y @chili3d/mcp status
npx -y @chili3d/mcp list
npx -y @chili3d/mcp call get_document_state
npx -y @chili3d/mcp shot shot.jpg

Using it

1. Call chili3d_open (or run chili3d-mcp open). It starts the bridge and opens the page; keep that tab in the foreground.

2. chili3d_status reports connected: true once the page has connected back.

3. The page's tools appear as chili3d_<tool> — chili3d_run_program, chili3d_get_document_state, chili3d_select_nodes, chili3d_capture_screenshot, chili3d_load_skill, and the rest.

4. A fresh page has no document: chili3d_new_document before modeling.

The catalogue is dynamic: chili3d_open and chili3d_status are always listed, and the page's tools appear after it connects (the server sends notifications/tools/list_changed). Clients that do not re-list on that notification need their session restarted once the page is connected.

How it works

The daemon lives in ~/.chili3d-mcp (session.json, daemon.log). chili3d-mcp stop ends it; it stays up across agent sessions so a page does not have to reconnect.

Security

• The daemon binds 127.0.0.1 only and rejects a non-loopback Host (DNS rebinding).

• The WebSocket accepts exactly one Origin: that of --app-url (https://chili3d.com by default, http://localhost:8080 for a local build). Another page on the same machine cannot take the seat and feed tool descriptions to the model.

• /rpc rejects any request carrying an Origin — browsers always send it, the MCP server and the CLI never do, so a web page cannot drive the bridge.

• There is no token: the page's origin is enforced by the browser, and local processes are already inside the user's trust boundary.

Development

npm install
npm test          # daemon+CLI smoke, then a real MCP client end-to-end
npm run check     # biome

Limitations

• The page must stay in the foreground; background tabs are throttled and screenshots go stale.

• One page at a time. A second page replaces the first.

• A call that times out does not disconnect the page: the seat stays busy and further calls fail until the page answers or reconnects, so a slow build never costs an unsaved document. chili3d-mcp status shows which tool it is waiting on.

• The external agent and the in-app chat panel have no lock between them — do not drive the same document from both at once.