MCP Server Installation

The UI Lab MCP server gives AI agents direct, structured access to the component library, design tokens, patterns, elements, and sections. Instead of pasting documentation into prompts, agents call tools to look up exactly what they need in real time.

How it works

The server implements the Model Context Protocol over stdio (stdin/stdout). When connected, AI agents can call 10 tools and read 4 resource types to discover and use UI Lab's design system.

The server is the ui-lab package and its executable is ui-lab-mcp. It runs as a child process that your AI client (Claude Desktop, Cursor, etc.) manages automatically. The ui-lab command is reserved for @ui-lab/cli.

Prerequisites

• Node.js ≥ 18 — the server is pure ES Module
• UI Lab installed in your project — see Installation

Quick start: Claude Desktop

Add this to your Claude Desktop config file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ui-lab": {
      "command": "npx",
      "args": ["--package", "ui-lab", "ui-lab-mcp"]
    }
  }
}

Restart Claude Desktop. The server connects automatically on startup.

Quick start: Cursor

Add to .cursor/mcp.json in your project root (or the global Cursor settings):

{
  "mcpServers": {
    "ui-lab": {
      "command": "npx",
      "args": ["--package", "ui-lab", "ui-lab-mcp"]
    }
  }
}

Quick start: Local install

If you prefer not to use npx, install the package directly:

pnpm add -D ui-lab
# or
npm install --save-dev ui-lab

Then point your client to the installed binary:

{
  "mcpServers": {
    "ui-lab": {
      "command": "node",
      "args": ["./node_modules/.bin/ui-lab-mcp"]
    }
  }
}

Verifying the connection

When the server starts successfully it logs to stderr:

[UI Lab MCP] Server started successfully
[UI Lab MCP] Listening for connections...

In Claude Desktop, the MCP icon in the chat input turns active when the server is connected. You can test it by asking Claude:

"Search for a button component using UI Lab tools"

Claude will call search_components and return structured results from the registry.

What the server exposes

Once connected, the agent has access to:

See Workflows for details on each tool.

Troubleshooting

Server doesn't start

Verify Node.js version:

node --version
# must be 18.x or higher

Test the server manually:

npx --package ui-lab ui-lab-mcp
# Should print: [UI Lab MCP] Server started successfully

If it hangs silently, the server is running and waiting for MCP protocol input over stdin — that's correct behavior.

"Module not found" errors

The registry package must be built. If you're running from a local monorepo clone:

pnpm --filter ui-lab-registry run build
pnpm --filter ui-lab run build

Claude doesn't call any tools

Verify the server name in config matches what you expect — Claude Desktop uses the key name (e.g., "ui-lab") as the server identifier. Check that the config file is valid JSON.

npx downloads every time

Install the package locally in your project and reference the local binary instead of using npx.

Running from source

If you're developing UI Lab itself or want to run the server from the monorepo:

cd packages/@mcp
pnpm build
node dist/index.js

Point your client config to the absolute path:

{
  "mcpServers": {
    "ui-lab": {
      "command": "node",
      "args": ["/absolute/path/to/packages/@mcp/dist/index.js"]
    }
  }
}

Next steps

• Workflows — all 10 tools, resource URIs, design guidelines, and example agent conversations
• Design System — understand the color token system the MCP enforces