MCP Server

Obi UI ships a built-in Model Context Protocol server. Connect it to Claude or any MCP-compatible AI tool and it will have live access to every component spec, design token, and pattern — so it uses the actual Obi UI API instead of guessing.

What the server exposes

The MCP server runs as a stdio process and exposes three resources and two tools. All data is read from the source files at request time — it is always current, never stale.

resourceobi://components

The full component registry — every slug, name, category, description, props, and dependency list.

resourceobi://tokens

Every design token — colors, spacing, motion, typography — as a structured JSON object.

resourceobi://patterns

The list of design pattern documents: accessibility guidelines, interactive state rules, and the visual design philosophy.

toolget_component_spec

Returns the full spec.md for a named component — props, variants, accessibility notes, and usage guidance.

toolget_pattern

Returns a named pattern document by slug — e.g. "accessibility" or "design".

Connecting to Claude

The MCP server runs as a local stdio process. To connect it to the Claude desktop app, add an entry to your claude_desktop_config.json. On macOS this file lives at ~/Library/Application Support/Claude/claude_desktop_config.json.

1. Build the server

cd /path/to/your/design-system
npx tsx mcp/server.ts

2. Add to claude_desktop_config.json

{
  "mcpServers": {
    "obi-ui": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/your/design-system/mcp/server.ts"]
    }
  }
}

Replace /absolute/path/to/your/design-system with the actual path to this repo on your machine.

3. Restart Claude

Quit and reopen the Claude desktop app. You should see obi-ui listed under connected MCP servers in the bottom-left of the chat window.

Other MCP clients

Any MCP-compatible client can connect to the server the same way. The server speaks the standard stdio transport, so it works with Claude Code, Cursor, Windsurf, or any other tool that supports MCP.

For Claude Code, add the server to your .claude/settings.json using the same mcpServers format as above.

How it changes your workflow

Without the MCP server, asking an AI to "build a form using Obi UI" is a gamble — it may hallucinate prop names, invent variants that don't exist, or use an old API it saw in training data.

With the server connected, Claude can call get_component_spec("Form") before writing any code. It gets the exact prop table, the correct import path, the variants that actually exist, and the accessibility guidance for that component. The result is code that works the first time.

The server also exposes the full accessibility and design pattern documents, so Claude understands the visual philosophy, token naming conventions, and overlay interaction rules — not just individual component APIs.

Keeping specs current

Each component has a spec.md file alongside its source code. The MCP server reads these files at request time — there is no build step and no cache to invalidate. When you update a component and update its spec, the server immediately returns the new information.

The spec format is documented in rules/new-component.md. Every spec must include: a one-line description, a props table, an interactive states section, accessibility notes, and the install command.