# Shadcn Svelte Mcp

> Mastra MCP server and tooling for the shadcn-svelte component docs and developer utilities.

- **Type:** MCP server
- **Install:** `agentstack add mcp-michael-obele-shadcn-svelte-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Michael-Obele](https://agentstack.voostack.com/s/michael-obele)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Michael-Obele](https://github.com/Michael-Obele)
- **Source:** https://github.com/Michael-Obele/shadcn-svelte-mcp

## Install

```sh
agentstack add mcp-michael-obele-shadcn-svelte-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# shadcn-svelte-mcp

[](https://github.com/Michael-Obele/shadcn-svelte-mcp/releases)
[](https://opensource.org/licenses/MIT)

[](https://cursor.com/en-US/install-mcp?name=shadcn-svelte&config=eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9zaGFkY24tc3ZlbHRlLW1jcC5zdmVsdGUtYXBwcy53b3JrZXJzLmRldi9hcGkvbWNwL3NoYWRjbi9zc2UifQ==)

Mastra MCP server and tooling that provides real-time access to shadcn-svelte component documentation and developer utilities using web scraping.

## Production Deployments

> [!IMPORTANT]
> **URL Update Notification:** Due to the migration and updates to the Mastra Cloud platform, the deployment URL has changed to the new `*.server.mastra.cloud` structure. If you are experiencing connection issues, please update your editor and CLI configurations to use `https://shadcn-svelte-mcp.svelte-apps.workers.dev` as the previous URLs are no longer active.

Cloudflare Workers is the primary deployment: zero cold start, high availability, fast tool discovery, and the same toolset over both transports.

| Transport | URL                                                              | Best for                                 |
| --------- | ---------------------------------------------------------------- | ---------------------------------------- |
| SSE       | https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/sse | Editors that keep long-lived connections |
| HTTP      | https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp | CLIs, scripts, and one-off calls         |

> [!NOTE]
> This project follows our [Code of ConTIPduct](CODE_OF_CONDUCT.md) and welcomes contributions! See our [Contributing Guidelines](CONTRIBUTING.md) for details.

This repository contains a Mastra-based MCP server that provides real-time access to shadcn-svelte component documentation using web scraping. Use it in your AI-powered code editor to get instant access to the latest shadcn-svelte component information directly from the official website.

## Table of Contents

- [shadcn-svelte-mcp](#shadcn-svelte-mcp)
  - [Production Deployments](#production-deployments)
  - [Table of Contents](#table-of-contents)
  - [🎉 Features](#-features)
  - [Bits UI Integration](#bits-ui-integration)
    - [AI-Optimized Content](#ai-optimized-content)
  - [🔧 UX Observations \& Suggestions](#-ux-observations--suggestions)
  - [Editor Setup](#editor-setup)
    - [Verification](#verification)
  - [CLI \& Agent Configuration](#cli--agent-configuration)
  - [Skills.sh Skill](#skillssh-skill)
    - [Install from GitHub](#install-from-github)
    - [Local validation](#local-validation)
    - [Expected skills.sh page](#expected-skillssh-page)
  - [Verification \& Quick Tests](#verification--quick-tests)
  - [Available Tools](#available-tools)
  - [Example Usage](#example-usage)
  - [Local Development](#local-development)
    - [Contents](#contents)
    - [Quick start (development smoke-test)](#quick-start-development-smoke-test)
  - [Developer Scripts](#developer-scripts)
  - [Project Architecture](#project-architecture)
    - [Core Components](#core-components)
    - [Key Features](#key-features)
  - [Conventions \& notes](#conventions--notes)
  - [Development tips](#development-tips)
  - [License](#license)
  - [Contributing](#contributing)
  - [Contact](#contact)

## 🎉 Features

- ✅ Production deployment on Cloudflare Workers
- ✅ **Five main MCP tools** for comprehensive shadcn-svelte ecosystem support (see 'Available Tools')
- ✅ **Bits UI API documentation** - Direct access to underlying component library API docs with AI-optimized content
- ✅ Advanced fuzzy search with typo tolerance and intelligent suggestions
- ✅ **Lucide Svelte icon search** - Browse and search ~1,600 icons (dynamic) with smart filtering
- ✅ Support for all major AI code editors (Cursor, Windsurf, VS Code, Zed, Claude Code, Codex)
- ✅ HTTP and SSE transport protocols
- ✅ Real-time web scraping from shadcn-svelte.com and bits-ui.com

## Bits UI Integration

shadcn-svelte components are built on top of [Bits UI](https://bits-ui.com), the underlying component library that provides the core functionality. This MCP server provides direct access to Bits UI's comprehensive API documentation through AI-optimized content endpoints.

### AI-Optimized Content

The `bits-ui-get` tool fetches content from Bits UI's dedicated `/llms.txt` endpoints, which provide:

- **Structured API reference tables** with Property/Type/Description/Details columns
- **Clean markdown formatting** optimized for AI consumption
- **Implementation details** and usage examples
- **Data attributes and event handlers** documentation
- **Navigation links** to related components

This ensures that AI assistants receive the most relevant and well-structured information for implementing shadcn-svelte components correctly.

## 🔧 UX Observations & Suggestions

- The `shadcn-svelte-icons` tool previously showed an awkward message "No icons found matching \"undefined\"" when explicit `names` were requested and none were found — this has been fixed so the response now shows `No icons found for names: ...` instead. ✅
- Imports in the `icons` tool are intentionally limited to the first 10 names in the response to keep usage snippets tidy; increase the `limit` if you need more icons returned (the snippet still only imports the first 10). 💡
- The icons tool now supports `importLimit` (default 10) and `limit` (default 100) to control how many icons are returned, and how many are included in `import` statements.
- The `shadcn-svelte-get` tool now respects an optional `packageManager` parameter and adjusts the installation snippet accordingly (`pnpm dlx`, `yarn dlx`, `npx`, `bunx`). ✅
- If you notice any remaining odd messages or install command inconsistencies, please file an issue — we keep the MCP server behavior stable but will gladly refine UX in following pull requests.

## Editor Setup

Cloudflare Workers is the recommended deployment for all editors. Use SSE for persistent editor connections and HTTP for one-off requests or scripts. VS Code users can open the Command Palette (`Cmd/Ctrl+Shift+P`) and run `MCP: Add server` to paste either URL.

Cursor

1. Open Cursor Settings (`Cmd/Ctrl` + `,`).
2. Navigate to "MCP" / "Model Context Protocol" and add a new server configuration.
3. Add either the SSE or HTTP endpoint shown below.

Cloudflare Workers — SSE example:

```json
{
  "shadcn-svelte": {
    "type": "sse",
    "url": "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/sse"
  }
}
```

Cloudflare Workers — HTTP example:

```json
{
  "shadcn-svelte": {
    "type": "http",
    "url": "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp"
  }
}
```

Windsurf

1. Edit `~/.codeium/windsurf/mcp_config.json`.
2. Add the SSE transport as shown:

```json
{
  "mcpServers": {
    "shadcn-svelte": {
      "url": "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/sse",
      "transport": "sse"
    }
  }
}
```

3. Save, restart Windsurf, then open `mcp.json` in Agent mode and click "start".

Use the HTTP variant if you need it:

```json
{
  "servers": {
    "shadcn-svelte": {
      "type": "http",
      "url": "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp"
    }
  }
}
```

Zed

1. Open Zed settings (`Cmd/Ctrl` + `,`).
2. Edit `~/.config/zed/settings.json` and add an entry under `context_servers`:

```json
{
  "context_servers": {
    "shadcn-svelte": {
      "source": "custom",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/sse"
      ],
      "env": {}
    }
  }
}
```

4. Save, restart Zed, and confirm the server shows a green indicator in the Agent panel. Zed also offers a UI flow via Settings → Agent to paste either endpoint without editing JSON.

VS Code

Two supported workflows (both work for either user/global settings or workspace/project settings):

- **Option A — Command Palette (quick):** Run `MCP: Add Server` (Ctrl/Cmd+Shift+P) and paste the SSE or HTTP URL. This is the simplest interactive flow and can be used from the global (user) or workspace context.

  Examples to paste:
  - SSE: `https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/sse`
  - HTTP: `https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp`

- **Option B — mcp-remote JSON (scriptable):** Create or update `.vscode/mcp.json` (or your user-level MCP config) to use the `mcp-remote` helper. This works equally well as a workspace or global config and is handy for reproducible setups.

  Example `.vscode/mcp.json` using `mcp-remote` (SSE):

  ```json
  {
    "mcpServers": {
      "shadcn-svelte": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/sse"
        ]
      }
    }
  }
  ```

  And for the HTTP transport replace the URL with the `/mcp` endpoint:

  ```json
  {
    "mcpServers": {
      "shadcn-svelte": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp"
        ]
      }
    }
  }
  ```

### Verification

- Use the Command Palette and run `MCP: List Servers` to view configured servers.
- Use `MCP: List Servers > Configure Model Access` to manage which models can use MCP servers.

## CLI & Agent Configuration

The same base URLs work across CLIs. **Cloudflare Workers is the recommended primary deployment** for the fastest responses with zero cold start.

Claude Code CLI (Anthropic)

- **Global settings** (`~/.claude/settings.json`):

  ```json
  {
    "mcpServers": {
      "shadcn-svelte": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp"
        ]
      }
    }
  }
  ```

- **Project-scoped override** (`.mcp.json`):

  ```json
  {
    "mcpServers": {
      "shadcn-svelte": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp"
        ]
      }
    }
  }
  ```

  Enable project servers with:

  ```json
  {
    "enableAllProjectMcpServers": true
  }
  ```

- **Command palette alternative:**

  ```bash
  claude mcp add --transport http shadcn-svelte https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp
  ```

- Use `/permissions` inside Claude Code to grant tool access if prompted.

OpenAI Codex CLI

Register the Cloudflare Workers endpoint for codex or use your own privately hosted MCP endpoint.

```bash
codex mcp add shadcn-svelte --url https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/sse
codex mcp list
```

Gemini CLI (Google)

1. Create or edit `~/.gemini/settings.json`:

   ```bash
   mkdir -p ~/.gemini
   nano ~/.gemini/settings.json
   ```

2. Add a configuration. Cloudflare Workers example:

   ```json
   {
     "mcpServers": {
       "shadcn-svelte": {
         "httpUrl": "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp"
       }
     }
   }
   ```

3. Prefer the `npx mcp-remote` command variant if your CLI version expects a command:

   ```json
   {
     "mcpServers": {
       "shadcn-svelte": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp"
         ]
       }
     }
   }
   ```

4. Restart the CLI to apply changes.

## Skills.sh Skill

This repository includes a publishable agent skill at `skills/shadcn-sveltekit-design/SKILL.md` for designing and implementing polished SvelteKit pages and reusable components with shadcn-svelte while grounding component choices in this MCP.

### Install from GitHub

```bash
npx skills add Michael-Obele/shadcn-svelte-mcp --skill shadcn-sveltekit-design
```

For GitHub Copilot specifically:

```bash
npx skills add Michael-Obele/shadcn-svelte-mcp --skill shadcn-sveltekit-design --agent github-copilot -g -y
```

### Local validation

```bash
npx skills add . --list
```

### Expected skills.sh page

Once this repository change is pushed to the public GitHub repository and indexed by the `skills` ecosystem, the skill should resolve at:

```text
https://skills.sh/Michael-Obele/shadcn-svelte-mcp/shadcn-sveltekit-design
```

The skill assumes the `shadcn-svelte` MCP server is already configured in the agent environment.

## Verification & Quick Tests

Use these checks after configuration. Prefer SSE for editor connections and HTTP for CLI probing.

- `claude mcp list`
- `codex mcp list`
- `npx mcp-remote https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp`
- `curl -I https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/mcp`
- `curl -N https://shadcn-svelte-mcp.svelte-apps.workers.dev/api/mcp/shadcn/sse`

Claude Code may prompt for tool permissions. Use `/permissions` or set `allowedTools` in `~/.claude.json` if needed.

## Available Tools

These are the tool IDs exposed by the MCP server:

| Tool                   | Use for                                                                    | Returns                                                |
| ---------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
| `shadcn-svelte-list`   | Inventory of components, blocks, charts, docs, and Bits UI primitives      | Markdown list                                          |
| `shadcn-svelte-get`    | Detailed lookup for components, blocks, charts, docs, and install snippets | Structured JSON; supports `packageManager`             |
| `shadcn-svelte-search` | Fuzzy discovery when you do not know the exact component or docs name      | Markdown summary plus structured results               |
| `shadcn-svelte-icons`  | Lucide icon discovery with install and import snippets                     | Markdown; supports `names`, `limit`, and `importLimit` |
| `bits-ui-get`          | Lower-level Bits UI API reference and implementation details               | Structured JSON from Bits UI `llms.txt` endpoints      |

Use `shadcn-svelte-get` first for known components or docs, `shadcn-svelte-search` when the exact name is unknown, and `bits-ui-get` only when you need lower-level primitive details.

## Example Usage

After installing the MCP server in your editor, you can ask your AI assistant:

- "Show me how to install the shadcn-svelte button component"
- "List all available shadcn-svelte components"
- "Find components similar to a date picker and tell me which ones actually exist"
- "List the available chart components"
- "How do I customize themes in shadcn-svelte?"
- "Find Lucide icons for user profile and settings"
- "Show me the Bits UI API details for Dialog"
- "Give me the install steps for dashboard-01 using yarn"

## Local Development

Want to run the MCP server locally or contribute to the project?

### Contents

- `src/` - Mastra bootstrap, MCP servers, tools, and agents
- `src/services/` - Web scraping services for real-time documentation fetching
- `src/mastra/tools/` - Tools that expose component discovery, fetching and utilities
- `src/mastra/agents/` - Specialized AI agent for shadcn-svelte assistance
- `scripts/` - Version management and automation scripts

### Quick start (development smoke-test)

1. Install dependencies (using your preferred package manager).

```bash
# npm
npm install

# or bun
bun install

# or pnpm
pnpm install
```

2. Run the development smoke-test (recommended):

```bash
# Starts Mastra in dev mode; this repo's smoke-test expects a short run to detect runtime errors
npm run dev
```

## Developer Scripts

- `npm run dev` - Start Mastra in development mode (recommended smoke-test).
- `npm run build` - Build the Mastra project for pro

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Michael-Obele](https://github.com/Michael-Obele)
- **Source:** [Michael-Obele/shadcn-svelte-mcp](https://github.com/Michael-Obele/shadcn-svelte-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-michael-obele-shadcn-svelte-mcp
- Seller: https://agentstack.voostack.com/s/michael-obele
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.