# 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, validated install command, or
Pro block search result.
4. The assistant applies the result in your project using 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 or Starwind Pro project. |
| `starwind_docs` | Fetches Starwind UI docs from starwind.dev, 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."
- "Find Pro pricing blocks and tell me which ones require a license."
- "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.

If a Pro block install fails, confirm whether the block is free or premium. Premium blocks require
Starwind Pro access and the setup steps in the [Installation guide](/docs/getting-started/installation/).