Marmo UIMARMO UI

Tools

Claude Plugin & MCP

How to install, use, and troubleshoot the Marmo UI Claude Code plugin and the MCP server it connects to. The fastest way for AI agents to write correct @marmoui/ui code.

Claude Plugin & MCP

The Marmo UI Claude Code plugin is the recommended way for engineers to use AI to build UI with @marmoui/ui. It bundles three things into a single install:

  1. A skill that auto-triggers whenever you ask Claude to build, edit, or review UI code.
  2. Five slash commands (/marmo-ui:init, /marmo-ui:marmo-build, /marmo-ui:override, /marmo-ui:design-md, /marmo-ui:prototype) for explicit workflows — see the command reference.
  3. The Marmo UI MCP server — a hosted service that streams the current design-system knowledge (every component, every prop, every pattern) into Claude's context.

The result: Claude stops hallucinating prop names, stops importing @chakra-ui/react, and starts producing code that compiles and matches your design system on the first try.

One install per developer, one time. Updates arrive automatically — no per-repo config, no env vars, no shell exports.

Architecture

                  ┌──────────────────────────────────┐
                  │      Your repo (any product app) │
                  │                                  │
                  │   Claude Code session            │
                  │   ─────────────────              │
                  │   Skill auto-loads               │
                  │   Slash command available        │
                  └─────────────┬────────────────────┘
                                │  HTTPS + Bearer token
                                ▼
                  ┌──────────────────────────────────┐
                  │   marmo-ui MCP server (hosted)  │
                  │   ──────────────────────────     │
                  │   • Component index (74+)        │
                  │   • Pattern catalog              │
                  │   • Prop signatures (live)       │
                  │   • Validators                   │
                  └─────────────┬────────────────────┘
                                │  Re-indexes on every push
                                ▼
                  ┌──────────────────────────────────┐
                  │   mahmoudilyan/marmoui repo      │
                  │   ──────────────────────────     │
                  │   • packages/ui/src/             │
                  │   • content/components/*.mdx     │
                  │   • content/patterns/*.mdx       │
                  └──────────────────────────────────┘

When you push a component change or update an MDX file, the deployed MCP rebuilds its index within ~2 minutes and every developer's Claude Code session automatically sees the new data on its next tool call. Nobody has to update anything.

Quick start

In Claude Code, run these two commands inside any repo:

/plugin marketplace add mahmoudilyan/marmoui
/plugin install marmo-ui@marmoui-plugins

When prompted for marmo_mcp_token, paste the team-wide bearer token (ask Dan for the token").

That's it. The MCP starts automatically on the next tool call.

You need GitHub read access to mahmoudilyan/marmoui for /plugin marketplace add to clone the marketplace catalog.

One-paste alternative

If you'd rather skip the prompt:

CLAUDE_PLUGIN_OPTION_MARMO_MCP_TOKEN=<paste-team-token-here> \
  claude plugin marketplace add mahmoudilyan/marmoui && \
CLAUDE_PLUGIN_OPTION_MARMO_MCP_TOKEN=<paste-team-token-here> \
  claude plugin install marmo-ui@marmoui-plugins

Same end state — token goes straight to the OS keychain.

Verify it's working

In Claude Code:

/plugin                       # confirm marmo-ui is in the enabled list
/mcp                          # confirm marmo-ui MCP is connected (green dot)

Then in chat:

List all Marmo UI components.

If you see 70+ components come back, you're good. If /mcp shows a red dot, jump to Troubleshooting.

Daily workflow

You don't need to do anything special — the skill auto-triggers on UI work. But it helps to know what's happening behind the scenes.

Auto-trigger (most common)

Whenever your prompt mentions any of:

  • @marmoui/ui, "Marmo components", "our design system"
  • "build a form", "build a page", "build a dashboard"
  • "make this look like our app"
  • "add analytics", "track this", "PostHog" (the skill also covers analytics layering)

…the marmo-ui skill auto-loads and walks Claude through the validated workflow:

  1. Check the MCP is fresh (get_knowledge_version).
  2. Read the rules (get_design_guidelines).
  3. Find the right primitive — call get_pattern for known layouts, otherwise search_components + get_component_info.
  4. Write the code.
  5. Validate with review_generated_code before returning.

You'll see Claude make these calls in the trace. That's the workflow.

Explicit slash command

For a heavyweight "do it the Marmo way" request:

/marmo-ui:marmo-build a settings page with workspace, notifications, and billing tabs

The slash command runs the same workflow, but doesn't depend on Claude inferring intent from your wording — useful when the prompt is short or ambiguous. All five commands are documented in the command reference below.

Direct MCP tool calls

You can also invoke MCP tools directly:

@marmo-ui get_pattern patternId="app-shell"
@marmo-ui search_components query="dropdown"
@marmo-ui get_component_info componentName="Button"

Useful for spot-checks ("what props does Badge accept?") without launching the full generation workflow.

Slash commands

Five commands ship with the plugin. You never have to use them — every command has a plain-text equivalent, because the marmo-ui skill auto-triggers on natural language. Slash commands exist for precision: they run the exact documented workflow without depending on Claude inferring intent from your wording.

CommandWhat it doesPlain-text equivalent
/marmo-ui:initBootstrap the project's design identity — detect brand basics from the codebase, interview for the gaps, write DESIGN.md"Set up a DESIGN.md for this project"
/marmo-ui:marmo-buildBuild UI following the full MCP-backed workflow (guidelines → patterns → props → validate)"Build a settings page with our design system"
/marmo-ui:overrideSet up the local ui/ wrapper folder, then override an @marmoui/ui component or create a custom one"Override DataTable with a custom default page size" / "Create a custom InvoiceCard component in our ui folder"
/marmo-ui:design-mdGenerate a portable DESIGN.md (brand color, type, tokens, component inventory) any AI agent can read"Generate a design brief for this project"
/marmo-ui:prototypeScaffold a shareable prototype with the comments + AI-edit overlay, deploy to Netlify, return a public URL"Spin up a shareable prototype of this flow"

/marmo-ui:init

First-run setup for a product app. Scans the repo for existing tokens (CSS custom properties, Tailwind config, fonts), asks only about what it couldn't detect (brand name, primary color, layout family, rounding, density, dark mode), and writes a DESIGN.md at the project root. Every agent — Claude, Cursor, Codex — reads that file to generate on-brand UI. Never overwrites an existing DESIGN.md.

/marmo-ui:init
/marmo-ui:init our brand is Acme, primary color #0F62FE, dark mode required

/marmo-ui:marmo-build

The explicit "build this the Marmo way" command. Runs the same five-step workflow the skill uses (verify MCP freshness → read guidelines → fetch pattern or component info → write code → validate with review_generated_code), but guaranteed — no reliance on the skill recognizing your prompt as UI work.

/marmo-ui:marmo-build a subscribers page with an Import CSV action and a data table

Use it when the prompt is short, ambiguous, or when a previous freeform attempt produced off-system code.

/marmo-ui:override

Customize the design system without forking it. On first run it sets up the wrapper convention: creates src/ui/index.ts re-exporting @marmoui/ui, records uiImportPath: "@/ui" in DESIGN.md, and offers to migrate existing imports. After that, app code imports UI from @/ui and overriding a component is one file plus one re-export line.

/marmo-ui:override DataTable            # override an existing component (wraps, doesn't fork)
/marmo-ui:override new InvoiceCard      # create an app-specific component in src/ui/

See Overriding Components for the full convention, the wrap-vs-fork guidance, and common mistakes.

/marmo-ui:design-md

Generates the same DESIGN.md artifact as /marmo-ui:init, but sourced from the design system itself rather than an interview — brand color, typography, tokens, and the component inventory pulled live from the MCP. The portable wedge: hand the file to any agent in any editor and it generates on-brand UI without an MCP connection.

/marmo-ui:design-md

/marmo-ui:prototype

Scaffolds a shareable prototype from the prototype starter, pre-wired with the comments + AI-edit overlay (@marmoui/prototype-overlay), deploys it to Netlify, and returns a public URL. Reviewers sign in with Claude to leave inline comments; the owner can make AI edits in select mode.

/marmo-ui:prototype an onboarding flow with a 3-step wizard

Using commands in plain text

Slash commands are shortcuts, not requirements. The skill watches for intent, so these are equivalent:

You typeWhat runs
/marmo-ui:override DataTableThe override workflow, explicitly
"I want to customize the DataTable in this app — set up an override"The skill recognizes the intent and follows the same workflow
/marmo-ui:marmo-build a billing pageThe build workflow, explicitly
"Build a billing page with our design system"Skill auto-triggers, same five steps

Prefer slash commands when you want guaranteed, reproducible behavior (onboarding docs, runbooks, CI prompts); plain text is fine for day-to-day work.

What's in the MCP — tool reference

Eight tools, each focused on a specific job:

ToolWhen the AI calls itWhat it returns
get_knowledge_versionOnce per session, before generating any UI{ gitSha, indexedAt, componentCount, patternCount, uptimeSeconds }
get_design_guidelinesMandatory first call before writing @marmoui/ui codeGeneration checklist, hard rules (no namespace sub-components, PageSection is self-closing, etc.), import conventions
list_componentsDiscovery — when the AI doesn't know what existsNames, descriptions, categories, prop counts for every component
search_componentsDiscovery — when the AI knows the use caseTop 5–8 components matching a keyword ("form", "table", "toast")
get_component_infoRequired before using any component for the first time in a sessionExact prop signatures, types, defaults, examples, common mistakes
get_patternWhen the task matches a known multi-component layoutValidated copy-pasteable code for app-shell, data-table-with-filters, form-with-validation, confirmation-dialog, dialogs-for-other-actions, posthog-tracking
review_generated_codeMandatory on every piece of code before returning to the user{ valid, errors[], warnings[], suggestedFixes[] } against live prop signatures
validate_component_usageWhen validating user-provided or existing code (not freshly generated){ valid, issues[] }

The tool descriptions are what tells Claude when to use each tool — they're tuned in the MCP server (apps/design-system-mcp/src/tools/index.ts).

What gets installed

After /plugin install, you have:

ItemLocationPurpose
The marmo-ui skillAuto-loaded in every Claude Code sessionWalks the AI through the validated workflow
Five /marmo-ui:* slash commandsAlways availableinit, marmo-build, override, design-md, prototype — see command reference
The marmo-ui MCP server connectionmcp_servers registryStreams design-system knowledge to Claude
marmo_mcp_tokenOS keychain (sensitive)Authenticates with the hosted MCP
mcp_url (optional override)OS keychainPoints the plugin at a fork or local server

You don't see any of this on disk — there are no per-repo .mcp.json or .env files to commit.

Updating

Updates are automatic. The plugin uses git-SHA versioning, which means every commit to mahmoudilyan/marmoui is a new version. Claude Code re-checks the marketplace on a schedule, and you'll be prompted to update when a new SHA lands.

Manual update:

/plugin update marmo-ui@marmoui-plugins

This re-pulls the plugin from the marketplace; your token stays in the keychain across updates.

Configuration

The plugin exposes two config values via Claude Code's userConfig:

KeyRequiredDefaultNotes
marmo_mcp_tokenyes—Sensitive (sensitive: true). Stored in OS keychain.
mcp_urlnohttps://mcp.marmoui.com/mcpOverride only when running against a fork or local MCP.

Changing the token or URL

There's no built-in reconfigure flow yet. Two options:

Option A — uninstall + reinstall (re-prompts for both values):

/plugin uninstall marmo-ui@marmoui-plugins
/plugin install marmo-ui@marmoui-plugins

Option B — one-paste with new values:

CLAUDE_PLUGIN_OPTION_MARMO_MCP_TOKEN=<new-token> \
CLAUDE_PLUGIN_OPTION_MCP_URL=<new-url> \
  claude plugin install marmo-ui@marmoui-plugins --force

Either way the previous keychain entry is overwritten.

Troubleshooting

MCP not connected (red dot in /mcp)

Most common cause: wrong or expired token. Reinstall to re-prompt:

/plugin uninstall marmo-ui@marmoui-plugins
/plugin install marmo-ui@marmoui-plugins

If reinstall doesn't fix it, the issue is server-side. Surface the error to the design-system team.

"SDK auth failed: HTTP 404 / Invalid OAuth error response"

This means the MCP server returned an HTML 404 instead of a JSON response — typically because the server's TEAM_API_KEY env var is unset or empty, so requests fall through to the docs site's 404 page. Server-side issue; ping the design-system team.

"401 Unauthorized" on tool calls

Your token doesn't match the server's TEAM_API_KEY. The team rotated the token, or you pasted the wrong value. Reinstall the plugin and paste the current team token.

"Tool not found: mcp__marmo-ui__*"

The plugin isn't enabled in this session. Run /plugin and confirm marmo-ui is in the enabled list. If it isn't, /plugin install marmo-ui@marmoui-plugins.

Stale component data

The MCP indexes from main. If you don't see a component you just merged, it hasn't redeployed yet (~2 min after merge). You can confirm by calling:

@marmo-ui get_knowledge_version

Compare gitSha to the latest commit on main. If they don't match, wait or check the deploy workflow on GitHub.

Two marmo-ui MCP entries showing in /mcp

You probably installed the plugin and also have the design-system contributor manual setup (.mcp.json + MARMO_MCP_TOKEN env var) active. They both register a server named marmo-ui — Claude Code can pick the wrong one. Pick one path:

  • Product engineers: keep the plugin, remove MARMO_MCP_TOKEN from your shell.
  • Design-system contributors: uninstall the plugin, keep the manual setup.

Cursor users

Cursor doesn't support Claude Code plugins, but it does support the same MCP server. Add a per-user MCP config at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "marmo-ui": {
      "url": "https://mcp.marmoui.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TEAM_API_KEY"
      }
    }
  }
}

Replace YOUR_TEAM_API_KEY with the team token. Restart Cursor.

The skill and slash command are Claude-Code-only, but the MCP tools (get_component_info, get_pattern, review_generated_code, etc.) work the same way in Cursor — just call them directly or let Cursor's agent use them.

Other MCP clients (Cline, Continue, Zed, …)

The server speaks standard MCP over Streamable HTTP. Configure your client with:

URL:    https://mcp.marmoui.com/mcp
Header: Authorization: Bearer <team-token>

No client-specific tweaks required.

For design-system contributors (manual setup)

If you're working inside mahmoudilyan/marmoui and changing the MCP itself, use the project-scoped config rather than the plugin:

echo 'export MARMO_MCP_TOKEN="<paste-token>"' >> ~/.zshrc
source ~/.zshrc

The repo-root .mcp.json interpolates this env var. Don't run this and the plugin — they declare the same server name and Claude Code may pick the wrong one.

The MCP server source lives in a private repository; you only ever connect to the hosted instance.

How knowledge stays fresh

Every merge to main in this repo flows to the hosted MCP automatically: CI rebuilds the MCP image (which pulls the latest public docs — component-props.json, component MDX, @marmoui/ui exports — plus the private patterns knowledge) and redeploys it. The MCP rebuilds its index on startup.

The pre-commit hook (.husky/pre-commit) keeps component-props.json in sync with component source, so the index never drifts from the real props.

For details on the authoring schema (frontmatter, required sections, cross-reference tables), see CONTRIBUTING-MDX.md.

Privacy & data flow

  • What leaves your machine? Tool call arguments (component name, pattern id, code snippets you ask Claude to validate). The MCP server logs the tool name, request id, and duration — not the raw argument bodies.
  • What's stored? Nothing user-identifying. The hosted MCP is stateless; restarts wipe everything but the indexed knowledge.
  • Where's the token? OS keychain only. Never in logs, never on disk, never in git.
  • Network egress? Your client → the hosted MCP over HTTPS. The MCP itself doesn't contact third parties during a tool call.

If your team has stricter data-residency requirements, the same MCP can run inside your network — point mcp_url at your hosted instance.

Reporting issues

  • Plugin / install issue: open an issue on mahmoudilyan/marmoui with the label claude-plugin.
  • Wrong / hallucinated component data: open an issue with the label mcp-bug and the offending tool call (the request id from the trace is enough to find it in server logs).
  • MDX content gap (component missing a "When to use" or cross-ref): open an issue with the label mdx-audit and link to the relevant content/components/*.mdx.

Related