# MCP Server

Use the Starwind UI MCP server to search Starwind UI, read current documentation, and generate
validated CLI commands from an MCP-compatible assistant. It supports Starwind UI v3 projects using
Astro or React.

The server is published as [@starwind-ui/mcp](https://www.npmjs.com/package/@starwind-ui/mcp) and
runs locally through your MCP client.

## Quick Start

Select your MCP client and add the configuration.

<DocsTabs defaultValue="codex" syncKey="ide" class="min-h-[150px]">
<DocsTabsList>
<DocsTabsTrigger value="codex">Codex</DocsTabsTrigger>
<DocsTabsTrigger value="claude">Claude Code</DocsTabsTrigger>
<DocsTabsTrigger value="cursor">Cursor</DocsTabsTrigger>
<DocsTabsTrigger value="opencode">OpenCode</DocsTabsTrigger>
<DocsTabsTrigger value="vscode">VS Code</DocsTabsTrigger>
<DocsTabsTrigger value="devin">Devin</DocsTabsTrigger>
</DocsTabsList>
<DocsTabsContent value="codex">
```toml title="~/.codex/config.toml"
[mcp_servers.starwind_ui]
command = "npx"
args = ["-y", "@starwind-ui/mcp"]
enabled = true
```
</DocsTabsContent>
<DocsTabsContent value="claude">
```json title=".mcp.json"
{
  "mcpServers": {
    "starwind-ui": {
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"],
      "env": {}
    }
  }
}
```
</DocsTabsContent>
<DocsTabsContent value="cursor">
```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "starwind-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"],
      "env": {}
    }
  }
}
```
</DocsTabsContent>
<DocsTabsContent value="opencode">
```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "starwind-ui": {
      "type": "local",
      "command": ["npx", "-y", "@starwind-ui/mcp"],
      "enabled": true
    }
  }
}
```
</DocsTabsContent>
<DocsTabsContent value="vscode">
```json title=".vscode/mcp.json"
{
  "servers": {
    "starwind-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"]
    }
  }
}
```
</DocsTabsContent>
<DocsTabsContent value="devin">
```json title=".devin/mcp_config.json"
{
  "mcpServers": {
    "starwind-ui": {
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"]
    }
  }
}
```

This project file configures Devin Local, the default agent in new Devin Desktop tabs. You can
also create it with `devin mcp add -s project starwind-ui -- npx -y @starwind-ui/mcp`.
</DocsTabsContent>
</DocsTabs>

After you add the configuration, reload the MCP server when your client requires it. Use the
client's MCP status view or list command to confirm that Starwind UI connected.

## What You Can Do

With the MCP server, an assistant can:

- Prepare a validated Starwind UI v3 initialization command for an Astro or React project.
- Search styled components, Primitives, and Starwind Pro blocks.
- Generate validated install commands for the selected framework and project.
- Fetch exact component, Primitive, Runtime, migration, and framework documentation.
- Check a legacy Astro project and prepare a safe Starwind UI v3 migration command.

The server inspects local project context when available. It returns commands for the assistant to
review with you. It does not run those commands.

## Available Tools

| Tool | Use it for |
| --- | --- |
| `starwind_init` | Prepare a Starwind UI v3 initialization command. |
| `starwind_search` | Find styled components, Primitives, and Pro blocks. |
| `starwind_add` | Prepare validated install commands. |
| `starwind_docs` | Read current Starwind documentation. |
| `starwind_migrate` | Check and guide a legacy Astro migration. |

## Example Prompts

- "Find a React combobox and show me its documentation."
- "Add button, card, and dialog to this Astro project."
- "Show me the Primitive and Runtime API for Color Picker."
- "Check whether this project needs the Starwind UI v3 migration."
- "Find free Starwind Pro hero blocks."

Use [Starwind Skills](/docs/getting-started/skills/) with MCP when your assistant supports both.
Skills provide editing guidance. MCP supplies current Starwind data and commands.

## Troubleshooting

If the tools do not appear, restart or reload the server from the client's MCP controls. Confirm
that the client can run:

```bash
npx -y @starwind-ui/mcp
```

If your client still shows `search_starwind_pro_blocks`, stop the old MCP process and restart the
client. Current releases use `starwind_search` for components, Primitives, and Pro blocks.

## Client Documentation

- [Codex MCP docs](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
- [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)
- [Cursor MCP docs](https://cursor.com/docs/mcp)
- [OpenCode MCP docs](https://opencode.ai/docs/mcp-servers/)
- [VS Code MCP docs](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
- [Devin Local MCP docs](https://docs.devin.ai/cli/extensibility/mcp/configuration)