shadcn-svelte-mcp

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

Production Deployments

Mastra Cloud is the primary deployment: zero cold start, fast tool discovery, and the same toolset over both transports.

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

[!NOTE]
This project follows our Code of Conduct and welcomes contributions! See our Contributing Guidelines 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.

Production Deployments
Features
Bits UI Integration
Observations & Minor UX Suggestions
Editor Setup
CLI & Agent Configuration
Skills.sh Skill
Verification & Quick Tests
Available Tools
Example Usage
Local Development
Developer Scripts
MCP Architecture
Project Architecture
Contributing
License
Contact

🎉 Features

✅ Production deployment on Mastra Cloud
✅ 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, 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

Mastra Cloud 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

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

Mastra Cloud — SSE example:

{
  "shadcn-svelte": {
    "type": "sse",
    "url": "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse"
  }
}

Mastra Cloud — HTTP example:

{
  "shadcn-svelte": {
    "type": "http",
    "url": "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp"
  }
}

Windsurf

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

{
  "mcpServers": {
    "shadcn-svelte": {
      "url": "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse",
      "transport": "sse"
    }
  }
}

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

Use the HTTP variant if you need it:

{
  "servers": {
    "shadcn-svelte": {
      "type": "http",
      "url": "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp"
    }
  }
}

Zed

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

{
  "context_servers": {
    "shadcn-svelte": {
      "source": "custom",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse"
      ],
      "env": {}
    }
  }
}

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.mastra.cloud/api/mcp/shadcn/sse
- HTTP: https://shadcn-svelte.mastra.cloud/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):

{
  "mcpServers": {
    "shadcn-svelte": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "shadcn-svelte": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shadcn-svelte.mastra.cloud/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. Mastra Cloud is the recommended primary deployment for the fastest responses with zero cold start.

Claude Code CLI (Anthropic)

Global settings (~/.claude/settings.json):

{
  "mcpServers": {
    "shadcn-svelte": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp"
      ]
    }
  }
}

Project-scoped override (.mcp.json):

{
  "mcpServers": {
    "shadcn-svelte": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp"
      ]
    }
  }
}

Enable project servers with:

{
  "enableAllProjectMcpServers": true
}

Command palette alternative:

claude mcp add --transport http shadcn-svelte https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp

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

OpenAI Codex CLI

codex mcp add shadcn-svelte --url https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse
codex mcp list

Gemini CLI (Google)

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

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

Add a configuration. Mastra Cloud example:

{
  "mcpServers": {
    "shadcn-svelte": {
      "httpUrl": "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp"
    }
  }
}

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

{
  "mcpServers": {
    "shadcn-svelte": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp"
      ]
    }
  }
}

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

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

For GitHub Copilot specifically:

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

Local validation

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:

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.mastra.cloud/api/mcp/shadcn/mcp
curl -I https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp
curl -N https://shadcn-svelte.mastra.cloud/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?

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)

Install dependencies (using your preferred package manager).

# npm
npm install

# or bun
bun install

# or pnpm
pnpm install

Run the development smoke-test (recommended):

# 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 production.
npm run start - Start the built Mastra server.
npm run check-versions - Check if package.json and mcp-server.ts versions match (fails if mismatched).
npm run sync-versions-auto - Check versions and auto-sync if mismatched (package.json is source of truth).
npm run sync-versions - Sync versions from latest git tag to both files.

Project Architecture

Core Components

Mastra Framework: Orchestrates agents, workflows, and MCP servers
MCP Server: Exposes tools to AI code editors via HTTP/SSE protocols
Web Scraping Services: Multi-strategy approach for fetching documentation:
- Direct .md endpoint fetching for shadcn-svelte components
- AI-optimized /llms.txt endpoint fetching for Bits UI API documentation
- Crawlee (Playwright) for JavaScript-heavy pages (charts, themes, blocks)
- Cheerio + Turndown for simple HTML pages
Intelligent Caching: 3-day TTL cache with memory and disk storage
Component Discovery: Dynamic scraping of component registry from shadcn-svelte.com
Advanced Search: Fuse.js-powered fuzzy search with typo tolerance

Key Features

The project combines real-time documentation fetching, Bits UI API access, multi-strategy scraping, intelligent caching, Lucide icon search, semantic version synchronization, and production deployment on Mastra Cloud.

Conventions & notes

Tools are implemented under src/mastra/tools and should use zod for input validation
Web scraping services are implemented under src/services/ and use Crawlee (with Playwright) for real-time documentation fetching from JavaScript-heavy pages
Intelligent caching is used to improve performance and reduce API calls
Tools follow Mastra patterns using createTool with proper input/output schemas

Development tips

Node >= 20.9.0 is recommended (see package.json engines)
When adding tools, follow the patterns in src/mastra/tools/shadcn-svelte-get.ts and shadcn-svelte-list.ts
After making changes, run the 10–15s smoke-test via npm run dev to surface runtime integration issues early
Set up proper Firecrawl API credentials for web scraping functionality
The system uses intelligent caching - clear cache if you need fresh data during development

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions! Please read our Contributing Guidelines and Code of Conduct before getting started.

Contact

Issues & Support: [email protected]
Contributions: [email protected]
Maintainer: Michael Obele ([email protected])

For more details:

MCP Prompts System: See MCP_Prompts_System.md for comprehensive documentation on the MCP prompt system
MCP Architecture: See MCP_ARCHITECTURE.md for detailed explanation of MCP server vs client
Web scraping services: See src/services/ for Crawlee-based real-time documentation fetching implementation
AI assistant guide: See .github/copilot-instructions.md

shadcn-svelte-mcp

shadcn-svelte-mcp

Production Deployments

Table of Contents

🎉 Features

Bits UI Integration

AI-Optimized Content

🔧 UX Observations & Suggestions

Editor Setup

Verification

CLI & Agent Configuration

Skills.sh Skill

Install from GitHub

Local validation

Expected skills.sh page

Verification & Quick Tests

Available Tools

Example Usage

Local Development

Contents

Quick start (development smoke-test)

Developer Scripts

Project Architecture

Core Components

Key Features

Conventions & notes

Development tips

License

Contributing

Contact

Yorumlar (0)