What is the Starwind UI MCP server?
The Starwind UI MCP server runs locally over stdio with npx -y @starwind-ui/mcp. It gives your agent five tools for Starwind UI v3 on Astro and React: init, add, search, docs and migrate. It generates the install commands but never runs them.
It is a TypeScript MCP server for Starwind UI v3 and Starwind Pro. It gives an AI coding agent current, framework-aware guidance for Astro and React projects, so the agent picks real components and the right install command instead of guessing from stale training data.
The server checks its data against the versioned Starwind AI manifest, caches what it validates, and falls back to a bundled v3 snapshot if the site is unreachable. For the registry-style alternative, see the shadcn MCP server.
What it changes in your workflow
- The agent searches styled components, primitives and Pro blocks with framework metadata and filters before it writes custom markup.
- It fetches exact docs for a component, primitive, the Runtime layer, migration or a framework.
- It generates init and add commands for your project, with the package manager detected locally when possible.
- No tool executes the generated command, so you read it and run it yourself.
The three Starwind v3 surfaces
| Surface | What it is | How the MCP handles it |
|---|---|---|
| Styled components | Copy-owned UI components with Astro and/or React versions | Search and install with starwind_search and starwind_add |
| Primitives | Lower-level Astro and React adapters | Search with the primitive surface, install with the v3 primitives add command |
| Runtime | Framework-neutral behavior APIs | Fetch with starwind_docs |
Who it is for
Best for
- Astro and React projects that use or plan to use Starwind UI v3.
- Teams moving a project from Starwind v2 to v3 who want guided, interactive migration steps.
- Developers who want free Pro catalog blocks found and installed from the agent.
Not for
- Vue, Svelte or other frameworks. The repo documents Astro 5+ and React 18+ projects only.
- Design file access. For Figma frames use Figma MCP.
- Rules for composing UI. Pair it with a skill such as the frontend-design skill for direction.
Use it with UiChemy
The server installs components into your own Astro or React front end. UiChemy covers the WordPress side. Composer is a visual editor for Elementor or Gutenberg, and AI to WordPress imports an existing AI build as an editable page. Click Get Started on uichemy.com.
Connect Starwind UI MCP Server: Astro and React Components to your AI client
npx -y @starwind-ui/mcpCheck Node.js
The commands the server generates need Node.js 22.12.0 or newer. The project itself should be an existing Astro 5+ or React 18+ app.
Add the server
Put the config above in .mcp.json for Claude Code or .cursor/mcp.json for Cursor.
Codex needs TOML
For Codex, add a [mcp_servers.starwind_ui] table to ~/.codex/config.toml with command npx, args -y and @starwind-ui/mcp, and enabled true.
Restart the client
Restart the client or reload its MCP servers after changing the config.
Try a prompt
Ask the agent to search Starwind for a dialog component and give you the add command for your framework.
Client configuration
{
"mcpServers": {
"starwind-ui": {
"command": "npx",
"args": ["-y", "@starwind-ui/mcp"]
}
}
}Endpoints and ports
npx -y @starwind-ui/mcpStarts the server over stdio. Your client normally runs it.https://starwind.dev/docs/getting-started/mcp/Maintained client setup guide.https://starwind.dev/ai-manifest.jsonVersioned manifest the server validates against.pnpm dlx starwind@latest setup --yesPrepares the Pro registry and .env.local for an existing Astro project.What you can do with it
- Framework-awareGuidance targets Astro 5+ and React 18+, and the init tool lets the Starwind CLI auto-detect the framework unless you pass one.
- Three surfaces kept distinctStyled components, primitives and the Runtime layer are searched and installed through different paths, so the agent does not mix them up.
- Validated and cached dataData is checked against the versioned AI manifest and cached, with a bundled v3 snapshot as a fallback.
- Commands, not executionEvery tool returns readable JSON text plus structured content, and none of them runs the command it generates.
- Free and paid Pro blocksFree Pro catalog blocks install after ordinary init. Paid blocks need explicit authorization, and search results carry an upgrade path.
- Guided v2 to v3 migrationThe migrate tool is interactive by default. Setting yes to true is meant only when backup-and-overwrite is intended.
- Package manager detectionAdd commands pass the package manager resolved from your project to the CLI.
Tools it exposes
starwind_init
Generates v3 initialization commands for an existing Astro or React project. Pro is opt-in.
starwind_add
Validates requests and generates install or deferred-install commands for styled components, primitives or Astro-only Pro blocks.
starwind_search
Searches styled components, primitives and Pro blocks with framework metadata and filters.
starwind_docs
Resolves exact docs for components, primitives, Runtime, migration and frameworks.
starwind_migrate
Inspects a project and generates safe, interactive-first v2 to v3 migration guidance.
Frequently asked questions
What is the Starwind UI MCP server?
It is a TypeScript MCP server that gives an AI coding agent current guidance for Starwind UI v3 and Starwind Pro on Astro and React projects. It searches components, fetches docs, generates install commands and helps migrate from v2.
How do I set up the Starwind UI MCP server?
Add a server entry with command npx and args -y and @starwind-ui/mcp to your client's MCP config, such as .mcp.json or .cursor/mcp.json, then restart the client. Codex uses a TOML table in its config file instead.
Does the server install components for me?
No. It generates the commands, and the README states that no tool executes them. You or your agent run the command in your project, which keeps the change visible in your terminal and your diff.
Does it work with React or only Astro?
It works with both. Starwind Pro blocks currently target Astro, so React searches omit them and React add requests reject them explicitly. Styled components have Astro and React implementations, so you pick the framework when you add them.
Do I need a Pro license?
Not to start. Free Pro catalog blocks work after ordinary initialization, and Pro stays opt-in. Paid blocks need explicit authorization with a license key stored in .env.local, which you should keep out of source control.
Which AI coding agents work with it?
The README shows setup for Codex, Claude Code and Cursor. Any other MCP client that can launch a stdio command should work with the same npx entry, but the README does not confirm that.
What does the migrate tool do?
It inspects your project and generates safe, interactive-first v2 to v3 migration guidance. Migration is interactive by default, and yes should be set to true only when you want backup-and-overwrite behavior.
How does it differ from the shadcn MCP server?
The shadcn MCP server works through registries defined in components.json. The Starwind server is specific to Starwind UI v3, with Astro and React support, Pro blocks and a migration tool.