# MCP Server

Use the Starwind UI MCP server to give compatible editors and AI tools live access to Starwind docs,
validated CLI commands, project context, customization guidance, and Starwind Pro block search.

The published MCP server is available as
[@starwind-ui/mcp](https://www.npmjs.com/package/@starwind-ui/mcp). It runs locally through your MCP
client and does not require this docs repo to be checked out.

## Quick Start

Select your MCP client and add the Starwind UI server 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="windsurf">Windsurf</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="windsurf">
```json title="mcp_config.json"
{
  "mcpServers": {
    "starwind-ui": {
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"],
      "env": {}
    }
  }
}
```
</DocsTabsContent>
</DocsTabs>

After adding the configuration, restart your editor or reload its MCP servers.

## What Is MCP?

[Model Context Protocol](https://modelcontextprotocol.io/) is an open protocol that lets AI
assistants connect to external tools and data sources. With the Starwind UI MCP server, an assistant
can ask Starwind-specific tools for docs, install commands, project context, customization guidance,
and Pro block search results.

## How It Works

1. Your MCP client starts `@starwind-ui/mcp` locally with `npx`.
2. The assistant calls Starwind MCP tools when it needs current docs, commands, or block metadata.
3. The server returns Starwind-specific data, such as a docs result or a validated install command.
4. The assistant applies the result in your project using the conventions from the docs and, when
installed, [Starwind Skills](/docs/getting-started/skills/).

## Available Tools

Current MCP tools include:

| Tool Name | Description |
| --- | --- |
| `starwind_init` | Generates an initialization command for a Starwind UI project. |
| `starwind_docs` | Fetches Starwind UI docs from this site, including topic-specific Markdown. |
| `starwind_add` | Generates validated install commands with package manager detection. |
| `search_starwind_pro_blocks` | Searches Starwind Pro blocks by query, category, or plan type. |

## Example Prompts

Once the MCP server is configured, try one of these prompts in your MCP-compatible assistant:

- "Show me the Starwind docs for select and dialog."
- "Generate the command to add button, card, and select to this project."
- "Search Starwind Pro for free hero blocks."
- "Get Starwind customization docs for dark mode and theme tokens."

## Detailed Client Instructions

- [Codex MCP docs](https://developers.openai.com/codex/mcp)
- [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/copilot/reference/mcp-configuration)
- [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)

## Troubleshooting

If your editor does not show Starwind MCP tools after adding the config, restart the editor or reload
the MCP server from the editor's MCP settings.

If the server install fails, make sure the client can run `npx -y @starwind-ui/mcp` and that Node.js
is available in the environment used by the editor.