@brilliant-hq/mcp

@brilliant-hq/mcp

No-config local MCP bridge for brilliant.design. Your coding agent drives your live Brilliant web tab (or the desktop app) with near-zero setup. Everything runs on 127.0.0.1 — zero bytes of MCP or design data touch Brilliant's servers.

Setup (once per machine, ever)

claude mcp add brilliant -- npx -y @brilliant-hq/mcp

stdio is the universal denominator, so the same package serves every MCP client (Claude Code, Codex, Gemini, Cursor, VS Code, Windsurf, Zed, Claude Desktop, …).

How it works

• The helper is a dumb router: MCP JSON-RPC crosses it verbatim; MCP semantics live in the Brilliant tab (or desktop app), never here.
• The first instance becomes the leader (owns one tab socket, one permission grant, one binding table); every other MCP client's helper is a follower that forwards over loopback /rpc. Leadership reassigns when the leader exits.
• No tab connected yet? Your first tool call opens brilliant.design and pairs via a URL fragment — discovery and pairing in one step.
• The Brilliant desktop app is detected on 127.0.0.1:3333/3334/3335 and covered by the same entry.

Full wire contract: PROTOCOL.md.

CLI

npx @brilliant-hq/mcp                          # run the stdio MCP server (default)
npx @brilliant-hq/mcp --version
npx @brilliant-hq/mcp install <client>         # add the server to <client>'s MCP config
npx @brilliant-hq/mcp install <client> --dry-run   # preview the change, write nothing
npx @brilliant-hq/mcp install <client> --remove    # remove it (exact inverse)

install merges into the tool's config without clobbering foreign servers, preserves JSONC comments, and is comment-/byte-stable on remove. Supported <client>: claude-code, cursor, vscode, codex, gemini, antigravity, windsurf, zed, opencode, claude-desktop. Per-client facts come from clients.json (the one shared table this package ships).

Security

• Every listener binds the 127.0.0.1 literal — never 0.0.0.0, never a scan of private ranges.
• The tab socket validates Origin: https://brilliant.design, a loopback Host (anti-DNS-rebinding), and a pairing token or an approved association.
• The pairing token is never served from any local endpoint; leader.json is mode 0600; the tab never reads it.

Requires Node ≥ 20.

Development

npm install
npm test        # node --test