What is Basecoat UI MCP?
Basecoat UI MCP is a local stdio server for Basecoat UI, the shadcn/ui look built without React. It serves curated component templates, macro layout blocks, rhythm and theming rules, and a static validator, all offline, so an AI coding agent assembles Astro, Next.js or HTML pages from known parts.
Basecoat UI MCP is an offline Model Context Protocol server for Basecoat UI, which gives the shadcn/ui look without React. Instead of scraping documentation, the agent queries a fixed registry of templates, layout blocks and rules for Astro, Next.js, HTML and Tailwind CSS 4.
It runs over local stdio with zero runtime network requests. Every macro and semantic response is bounded to 1,999 UTF-8 bytes, and larger result sets come back through cursors, so a reply is never cut off in the middle of JSON.
What changes in your agent's output
- Pages are built from 41 curated templates, from accordion and alert through card, chart, checkbox and combobox, instead of hand-written markup.
- Layouts come from named blocks such as
app-shell,auth-sign-inandpricing-tiers, plus six multi-block recipes likeworkspace-dashboard. - Spacing, type and surface choices follow rhythm rules, with the semantic token kept apart from the approved Tailwind utility.
- Generated Astro or HTML is checked by
validate_compositionbefore you review it.
Design sessions and validation
- Call
begin_designto open a persistent session that pins its profile and registry revision. - Instantiate a recipe with
apply_design_patch, passing anexpectedRevisionand an idempotentoperationId. - Write the component leaves in your own project, then record finished regions with
record_written. - Finish with
validate_designin complete mode andvalidate_compositionon the generated source.
Who it is for
Best for
- Astro, Next.js and plain HTML projects on Tailwind CSS 4 without a React runtime. Related: shadcn-mcp.
- Teams that keep a
DESIGN.md, which the server reads on demand throughbasecoat://project/context. Related: design-md. - Agents that need a repeatable theming contract, including all 8 style packs and class based dark mode.
Not for
- Anyone who wants React components. The README positions Basecoat as the no React route.
- Projects that need runtime behavior from the server. The host application owns rendering, data, authentication and sessions.
- Accessibility certification. The validator does not render, execute code or certify accessibility.
Use it with UiChemy
Basecoat output is plain HTML and Tailwind, so it carries over to WordPress more easily than React does. UiChemy's AI to WordPress imports an AI build, and Composer edits it inside Elementor or Gutenberg. Click Get Started on uichemy.com.
Connect Basecoat UI MCP: Offline shadcn Look Without React for AI Agents to your AI client
claude mcp add basecoat-ui -- npx -y @intellmedia/basecoat-ui-mcp --project-root $(pwd)Check Node
The README requires Node.js 22.14.0 or newer.
Register the server
Run the command above in Claude Code, or paste the JSON into
.cursor/mcp.jsonfor Cursor. Claude Desktop takes the same block with an absolute project path.Point it at your project
Set
--project-rootto the host application. It takes precedence overBASECOAT_PROJECT_ROOT, which takes precedence over the launch directory.Optional rules file
Copy
templates/cursor/basecoat-designer.mdcinto.cursor/rulesfor agent guidance. The server never writes your application source.
Client configuration
{
"mcpServers": {
"basecoat-ui": {
"command": "npx",
"args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "${workspaceFolder}"]
}
}
}Endpoints and ports
basecoat://project/contextReads DESIGN.md, capped at 6,000 UTF-8 bytesbasecoat://design/themingToken contract, 8 style packs, dark modebasecoat://design/rhythmSpacing, typography and structure rulesbasecoat://integration/frameworksAstro, Next.js, Express, Vite, Tailwind CSS 4What you can do with it
- 41 curated templatesThe checked-in Basecoat 1.0.2 registry holds 41 templates, each available as Astro or HTML with dependency notes.
- Macro layout blocksShells, authentication, dashboard, settings, forms, data and marketing blocks come with slots, ports and rules.
- Six multi-block recipesRecipes such as
workspace-dashboardandauth-split-flowassemble several blocks in one patch. - Persistent design sessionsSessions live under
.basecoat/designer/and keep using the registry revision they were pinned to. - Theming contractAll 8 official style packs, class based dark mode through
window.basecoat.themeand a no flash bootstrap are documented. - Static validationTheme rules such as
theme-strategy-mixedandtheme-storage-keyflag a second theme resolver before it ships. - Offline by designNo runtime network requests, and the published package starts from a read only install.
Tools it exposes
search_components
Returns up to 8 compact summaries of id, name and intent. Never returns markup.
get_component_details
Returns one Astro or HTML template with dependencies and composition guidance.
validate_composition
Statically checks up to 256 KiB of HTML or Astro and returns at most 24 issues.
search_macro_blocks
Finds blueprint blocks by query, role, family or tag.
get_macro_block
Reads one block section such as manifest, structure, slots, ports, rules or provenance.
begin_design
Creates a persistent design session pinned to a profile and registry revision.
get_design_context
Reads session lists or focused views such as overview, graph, rules, focus and next.
apply_design_patch
Applies atomic graph changes using expectedRevision and an idempotent operationId.
validate_design
Validates a draft or complete design graph and pages its diagnostics.
get_rhythm_rules
Returns approved spacing, typography, surface, border and layout patterns by profile and family.
get_fsm_recipe
Returns states, events, transitions, guards and actions for dialog, navigation, auth-flow and tabs.
Frequently asked questions
What is Basecoat UI MCP?
Basecoat UI MCP is an offline Model Context Protocol server for Basecoat UI, a shadcn/ui look without React. It exposes 41 templates, macro layout blocks, rhythm and theming rules and a static validator over local stdio, aimed at Astro, Next.js and HTML projects.
How do I install Basecoat UI MCP?
With Node.js 22.14.0 or newer, run npx -y @intellmedia/basecoat-ui-mcp --project-root $(pwd) from a client entry. Cursor and desktop clients use a JSON block with the same npx arguments. You can also add it globally or build from source.
Does Basecoat UI MCP need a network connection?
No. The README states the server makes zero runtime network requests and the package contract test starts it under a network tripwire. The registry snapshot ships inside the package, and importing blocks from shadcn style sources is a local, dry run friendly maintainer step.
What does validate_composition actually check?
It statically checks up to 256 KiB of HTML or Astro source and returns at most 24 issues, with optional semantic and density profiles. It does not render pages, execute code, resolve application modules or certify accessibility, so treat it as a lint pass.
Where do design sessions get stored?
Sessions persist under <project-root>/.basecoat/designer/ in the host project, so back that folder up if sessions matter to your workflow. The server does not walk parent directories and never writes host application source files.
Which agents can use it?
The README shows setup for Cursor, Claude Desktop and Claude Code, plus a generic npx block for any MCP client. Topics also list Windsurf. The server exposes stdio only, so a client must be able to launch a local process.
How is it different from the shadcn MCP server?
Basecoat serves a React free template set with curated layout contracts of its own. Its macro layer covers shells, auth flows and data workspaces, and those layout contracts are not supplied automatically by shadcn or by MCP. Related: shadcn-mcp and shadcn-ui-mcp.
Can it style Tailwind CSS 4 projects?
Yes. The integration resource covers Astro, Next.js, Express, Vite and Tailwind CSS 4, including style pack imports such as @import "basecoat-css/vega";. The server offers curated templates, macro layouts, rhythm tokens and static validation for Astro, Next.js, HTML and Tailwind CSS 4. Related: tailwind-design-system.