Design Lounge MCP

Design Lounge as an MCP server. Your agent can:

• Design from the library: 600+ piece briefs, 80+ themes, 40+ type pairings, 40+ recipes with directions, Lounge Icons, and Sanzo Wada's colour combinations. It picks a direction the same way every time and keeps two sites from looking alike.
• Remove AI giveaways: stock copy, em dashes, icon-card trios, gradients, the indigo palette, emoji icons, made-up numbers, and drift from the locked theme, pairing, and family.
• Get found and quoted: SEO, AEO (answer engines), and GEO (ChatGPT, Claude, Perplexity, Gemini). It checks the head, the share card, robots.txt for search and AI crawlers, server-rendered text, and JSON-LD.
• Look at the page: Chromium at 1280×800 and 390×844 with reduced motion. It runs axe, measures faces, labels, primaries, and tap targets, and saves the screenshots.

The server reads the same skills/design-lounge folder as the skill, so the rules live in one place. The skill is the method. The server does the parts that prose cannot: search, deterministic picks against the history, pictures of every piece, theme, and pairing, and checks that read and render the page.

The skill comes with it

Installing the server installs the skill. When the server starts, it puts the skill in ~/.agents/skills/design-lounge and links it into the skills folder of each client on the machine: Claude Code (~/.claude/skills), Cursor (~/.cursor/skills), and Codex (~/.codex/skills). That is the same layout the skills CLI uses. Clients that load skills then have the whole method before they design. Reload the client once after the first start.

• It updates its own copy when the server updates.
• It leaves alone a copy that something else installed, such as npx skills add or a hand edit, and says so. install_skill with replace: true swaps it for the server's copy.
• install_skill with project_path also copies it into a project's .claude/skills, .cursor/skills, and .agents/skills, for clients that only read project skills.
• In a client with no skill support, start_design returns the rules that must hold (their words win, the Rules list, and the Look fails), read from the same files, and read_guide serves the rest.
• DESIGN_LOUNGE_SKILL_INSTALL=off turns the install off.

Add it to your agent

Claude Code

claude mcp add design-lounge --scope user -- npx -y design-lounge-mcp@latest

Cursor (~/.cursor/mcp.json), Windsurf, Claude Desktop (claude_desktop_config.json), and other clients that take this shape:

{
  "mcpServers": {
    "design-lounge": { "command": "npx", "args": ["-y", "design-lounge-mcp@latest"] }
  }
}

VS Code (.vscode/mcp.json):

{ "servers": { "design-lounge": { "type": "stdio", "command": "npx", "args": ["-y", "design-lounge-mcp@latest"] } } }

Codex (~/.codex/config.toml):

[mcp_servers.design-lounge]
command = "npx"
args = ["-y", "design-lounge-mcp@latest"]

@latest makes each start check for a new release, so library updates reach you without reinstalling. Reload the client once after the first start, so it picks up the skill the server installs.

The rendered checks (screenshots, axe, measured labels and buttons, theme boards and type specimens) need a headless Chromium. Ask your agent to run install_browser once (about 100 MB), or run npx playwright install chromium --only-shell. Without it, every other check still runs, and the report says it did not look.

Hosted, for Claude.ai, ChatGPT, and other clients that cannot run a local program: add https://www.designlounge.live/api/mcp as a custom connector (Streamable HTTP, no sign-in). It has the library, start_design, the picks, and the static review of public URLs or pasted HTML. It leaves out what needs your machine: file paths, the history file, the skill and browser installs, and the rendered checks. It fetches only public addresses and allows 60 requests a minute per address. Pass your own recent picks as history if you keep them.

To run it from a clone of the repo instead: cd mcp && pnpm install, then use node /path/to/designs/mcp/src/server.mjs as the command.

Tools

Every review tool takes path (a file, or a folder with index.html), url (live or localhost), or html. For a path, it reads DESIGN.md beside the page or above it to learn the locked theme, pairing, family, Free mode, and Named aesthetic. A Named aesthetic lifts the bans it lists.

The server also offers three prompts, design, review, and deslop, and the method files as resources at lounge://guide/<file>.

What it writes, and what leaves your machine

• The skill. On start, it writes the skill to ~/.agents/skills/design-lounge and links it into ~/.claude/skills, ~/.cursor/skills, and ~/.codex/skills for the clients you have. A copy it did not make is never replaced. DESIGN_LOUNGE_SKILL_INSTALL=off turns this off. To remove it, delete those folders.
• Recent picks. record_pick appends a line to ~/.design-lounge/history.jsonl, so two sites you make do not come out alike. Nothing else reads it.
• Cached images. Theme boards and type specimens are cached in ~/.cache/design-lounge/boards. Screenshots go to your temp folder, or to out_dir.
• The hosted endpoint keeps nothing. Each request gets a fresh server, and the pages it reviews are fetched and dropped.
• The network. A review fetches the page you name, its stylesheets, robots.txt, sitemap.xml, llms.txt, and the share image, from your machine. Google Fonts loads for type specimens. Thumbnails and demos are bundled; designlounge.live is asked only for one that is missing. Nothing is sent to Design Lounge, and there is no tracking.

Settings

Develop

pnpm test                              # unit tests and a stdio round trip
pnpm release patch --dry-run           # sync the skill, test, and pack, without publishing
node test/client.mjs                   # list the tools
node test/client.mjs review_page '{"path":"test/fixtures/slop.html"}'

pnpm release patch (or minor, major, x.y.z, with --otp <code> for npm 2FA) syncs the skill from the library, runs the tests, bumps package.json and server.json together, publishes to npm and the MCP Registry, then commits and tags. It never pushes.

pnpm pack first copies the skill folder into skill/, and the thumbnails and demos into assets/ (scripts/bundle.mjs), so the published package carries the library and the pictures. About 12 MB packed.

Designed using Design Lounge by Susan Acharya.