MCP Server
Use the Spectrum UI MCP server to browse, search, and install components from your AI assistant.
The Spectrum UI MCP server lets AI assistants interact with the component registry. You can browse available components, search for specific ones, and install them directly into your project using natural language.
For example, you can ask an AI assistant to "Build a landing page using Spectrum UI components" or "Add the kanban board to my project".
The server runs via npx from the @spectrumui/mcp package — no global install needed.
Quick Start
Select your MCP client and follow the instructions to configure the Spectrum UI MCP server. If you'd like to do it manually, see the Configuration section.
Run the following command in your project:
claude mcp add spectrum-ui -- npx -y @spectrumui/mcpRestart Claude Code and try the following prompts:
- Show me all available components in the Spectrum UI registry
- Add the kanban board and animated drawer to my project
- Build a testimonial section using Spectrum UI components
Note: You can use the /mcp command in Claude Code to debug the MCP server.
What is MCP?
Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely connect to external data sources and tools. With the Spectrum UI MCP server, your AI assistant gains direct access to:
- Browse Components — list every component in the Spectrum UI registry, optionally filtered by category
- Search the Registry — find components by name or functionality, ranked by relevance
- Install with Natural Language — add components using simple conversational prompts like "add a login form"
- Get Component Details — full metadata, dependencies, and install instructions for any component
How It Works
When you ask your assistant for a component, it calls one of the MCP tools. The server fetches the latest registry from spectrumhq.in, and for installs it runs the shadcn CLI under the hood — trying bunx first, then falling back to npx automatically:
# What runs behind the scenes (Bun): bunx --bun shadcn@latest add @spectrumui/<component-name> # Fallback (npm/pnpm/yarn): npx shadcn@latest add @spectrumui/<component-name>
You can also run these commands manually — they're shown on every component's docs page in the Installation section.
Available Tools
The MCP server exposes five tools to your AI assistant:
| Tool | Description |
|---|---|
list_components | List all components, optionally filtered by category |
search_components | Fuzzy search by keyword, ranked by relevance |
get_component | Full metadata and install instructions for a specific component |
list_categories | All categories (AI, Forms, Animation…) with component counts |
install_component | Runs the CLI to install directly into your project |
Configuration
All clients share the same server definition — a command plus its arguments. Add it to your client's MCP config file:
{
"mcpServers": {
"spectrum-ui": {
"command": "npx",
"args": ["-y", "@spectrumui/mcp"]
}
}
}Each client reads its configuration from a different location:
| Client | Config file |
|---|---|
| Claude Code | .mcp.json (project root) |
| Claude Desktop | claude_desktop_config.json |
| Cursor | .cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| VS Code | .vscode/mcp.json |
Example Prompts
Browse & Search
- "Show me all available components in the Spectrum UI registry"
- "Search for an animated card in Spectrum UI"
- "What categories does Spectrum UI have?"
Install Components
- "Install the kanban board from Spectrum UI into my project"
- "Add the button, dialog and card components to my project"
- "Create a contact form using Spectrum UI components"
Component Details
- "Get details for the event-calendar component"
- "What dependencies does the animated drawer need?"
Requirements
| Requirement | Details |
|---|---|
| Node.js | v18 or higher |
| Package manager | npm, pnpm, yarn, or bun |
| Project stack | Next.js + Tailwind CSS + shadcn/ui (for install_component) |
| AI editor | Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, or any MCP-compatible editor |
Troubleshooting
MCP Not Responding
Make sure you fully quit and restarted your editor — in Claude Desktop, right-click the dock icon and choose Quit, not just close the window. In Claude Code, run /mcp to check the server status.
Installation Failures
Run the install command manually in your terminal first to confirm shadcn is set up. You need a components.json file at your project root.
Registry Access Issues
The MCP server fetches the latest registry from spectrumhq.in. Check your internet connection, or open an issue on GitHub.
Server Not Showing in Cursor
The mcp.json file must be in the .cursor/ folder at your project root (not a global location). Reload the window after adding it.