by Michael-Obele
Provides real-time access to shadcn-svelte component documentation and developer utilities via web scraping, exposed through an MCP server with HTTP and SSE transports.
Shadcn Svelte MCP delivers instant, programmatic access to the official shadcn-svelte component library documentation, icons, and search capabilities. It runs a Model Context Protocol (MCP) server that scrapes the upstream website in real time, caches results, and exposes four dedicated tools for AI‑powered code editors and CLI utilities.
https://shadcn-svelte.mastra.cloud) or backup Railway (https://shadcn-svelte-mcp.up.railway.app)./api/mcp/shadcn/sse/api/mcp/shadcn/mcpnpx mcp-remote https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp
curl -I …/mcp or npx mcp-remote … should return JSON tool metadata.shadcn-svelte-list, shadcn-svelte-get, shadcn-svelte-icons, shadcn-svelte-search.Q: Which host should I use for production?
A: Mastra Cloud (https://shadcn-svelte.mastra.cloud) is recommended for zero cold start and maximum responsiveness. Railway is only a backup.
Q: Do I need an API key? A: No API key is required for the public endpoints.
Q: What if the first Railway request fails? A: Wait a second and retry – the cold start clears almost instantly.
Q: Can I use the server locally?
A: Yes. Clone the repo, run npm install and npm run dev to start a development instance.
Q: Which transport is best for VS Code?
A: SSE (/sse) is preferred for editors that keep a persistent connection; HTTP works for one‑off commands.
Mastra MCP server and tooling that provides real-time access to shadcn-svelte component documentation and developer utilities using web scraping.
Choose the base host that fits your workflow — both expose the same toolset, but their runtime characteristics differ:
| Host | Base URL | Highlights |
|---|---|---|
| Mastra Cloud | https://shadcn-svelte.mastra.cloud | Primary choice - Zero cold start, maximum responsiveness, and consistently reliable performance. Tool discovery issue has been fixed. |
| Railway | https://shadcn-svelte-mcp.up.railway.app | Backup option with consistent tool visibility. Expect a split-second cold start; the very first request might fail and then succeed on retry. Alternate base host: https://shadcn-svelte-mcp-api.up.railway.app. |
/api/mcp/shadcn/sse for the SSE transport (best for editors that keep long-lived connections)./api/mcp/shadcn/mcp for the HTTP transport (handy for CLIs and quick one-off calls).https://shadcn-svelte-mcp-api.up.railway.app and append the same /api/mcp/shadcn/{sse|mcp} path.[!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.
Mastra Cloud is the recommended primary deployment for all editors. It offers zero cold start and maximum responsiveness. SSE works best for editors that keep a persistent connection, while HTTP is handy for one-off requests and scripts. VS Code users can open the Command Palette (Cmd/Ctrl+Shift+P) and run MCP: Add server to paste either URL.
Cmd/Ctrl + ,).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"
}
}
You can swap in the Railway host if you prefer guaranteed tool visibility:
- "url": "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse"
+ "url": "https://shadcn-svelte-mcp.up.railway.app/api/mcp/shadcn/sse"
~/.codeium/windsurf/mcp_config.json.{
"mcpServers": {
"shadcn-svelte": {
"url": "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse",
"transport": "sse"
}
}
}
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"
}
}
}
You can swap in the Railway host if you prefer guaranteed tool visibility:
- "url": "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse"
+ "url": "https://shadcn-svelte-mcp.up.railway.app/api/mcp/shadcn/sse"
Cmd/Ctrl + ,).~/.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": {}
}
}
}
{
"context_servers": {
"shadcn-svelte": {
"source": "custom",
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://shadcn-svelte-mcp.up.railway.app/api/mcp/shadcn/mcp"
],
"env": {}
}
}
}
You can swap in the Railway host if you prefer guaranteed tool visibility:
- "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse"
+ "https://shadcn-svelte-mcp.up.railway.app/api/mcp/shadcn/sse"
The same base URLs work across CLIs. Mastra Cloud is the recommended primary deployment for the fastest responses with zero cold start. Railway serves as a reliable backup option.
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 shadcn-svelte --url https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp
claude mcp add shadcn-svelte --url https://shadcn-svelte-mcp.up.railway.app/api/mcp/shadcn/mcp
Use /permissions inside Claude Code to grant tool access if prompted.
You can swap in the Railway host if you prefer guaranteed tool visibility:
- "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp"
+ "https://shadcn-svelte-mcp.up.railway.app/api/mcp/shadcn/mcp"
Register either endpoint:
codex mcp add shadcn-svelte --url https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse
codex mcp list
Swap in the Railway host if you prefer guaranteed tool visibility:
- --url https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sse
+ --url https://shadcn-svelte-mcp.up.railway.app/api/mcp/shadcn/sse
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"
]
}
}
}
Mastra Cloud is recommended for zero cold start and maximum responsiveness. Restart the CLI to apply changes. Railway serves as a backup option.
You can swap in the Railway host if you prefer guaranteed tool visibility:
- "https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp"
+ "https://shadcn-svelte-mcp.up.railway.app/api/mcp/shadcn/mcp"
claude mcp listcodex mcp listnpx mcp-remote https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcpcurl -I https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcpcurl -N https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/sseIf the Railway check fails on the first attempt, wait a moment and retry; the cold start clears almost immediately. Claude Code may prompt for tool permissions — use /permissions or set allowedTools in ~/.claude.json. Editors that maintain long-lived connections should use the SSE URL; quick scripts can stick with HTTP.
The tool discovery issue has been fixed for Mastra Cloud (https://shadcn-svelte.mastra.cloud), which can now be used reliably as the primary deployment. Use the Railway host below only as a backup when Mastra Cloud is experiencing downtime. The toolset is identical; only the host name differs. Expect a split-second cold start for the Railway deployment.
{
"shadcn-svelte-backup": {
"url": "https://shadcn-svelte-mcp.up.railway.app/api/mcp/shadcn/sse",
"type": "http"
}
}
Use this backup when:
https://shadcn-svelte.mastra.cloud) is experiencing downtime.Note: The previous 'utility' tool has been split into dedicated tools. Use
shadcn-svelte-iconsfor icon browsing/search,shadcn-svelte-listandshadcn-svelte-getfor discovery and docs, andshadcn-svelte-searchfor fuzzy search.
Once installed, your AI assistant will have access to these tools (IDs exactly as exposed by the MCP server):
shadcn-svelte-list — List components, blocks, charts, and docs (returns Markdown lists)shadcn-svelte-get — Retrieve detailed component/block/doc content as structured JSON (content, metadata, codeBlocks)shadcn-svelte-icons — Browse and search Lucide Svelte icons by name/tag (returns Markdown with install + usage snippets; uses dynamic upstream icon data)shadcn-svelte-search — Fuzzy search across components and docs (returns Markdown for display and a results array for programmatic use)shadcn-svelte-list: Markdown list intended for human display (component names, docs, blocks)shadcn-svelte-get: Structured JSON with content, metadata, codeBlocks (useful for programmatic responses)shadcn-svelte-icons: Markdown list with icon names, tag summaries, and an example @lucide/svelte usage snippetshadcn-svelte-search: An object with markdown, results (structured), and totalResultsAfter installing the MCP server in your editor, you can ask your AI assistant:
shadcn-svelte-icons toolshadcn-svelte-search tool (returns markdown and structured results)Want to run the MCP server locally or contribute to the project?
src/ - Mastra bootstrap, MCP servers, tools, and agentssrc/services/ - Web scraping services for real-time documentation fetchingsrc/mastra/tools/ - Tools that expose component discovery, fetching and utilitiessrc/mastra/agents/ - Specialized AI agent for shadcn-svelte assistancescripts/ - Version management and automation scripts# npm
npm install
# or bun
bun install
# or pnpm
pnpm install
# Starts Mastra in dev mode; this repo's smoke-test expects a short run to detect runtime errors
npm run dev
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.This project exposes a production-ready MCP Server that makes shadcn-svelte documentation and tools available to AI code editors.
What this means:
src/mastra/mcp-server.ts) - Exposes four shadcn-svelte tools to external MCP clients (Cursor, Windsurf, VS Code, etc.)The server is deployed at https://shadcn-svelte.mastra.cloud and exposes tools via HTTP and SSE transports.
For a detailed explanation of MCP concepts, see MCP_ARCHITECTURE.md.
.md endpoint fetching for componentssrc/mastra/tools and should use zod for input validationsrc/services/ and use Crawlee (with Playwright) for real-time documentation fetching from JavaScript-heavy pagescreateTool with proper input/output schemasThe project includes a comprehensive test suite covering:
package.json engines)src/mastra/tools/shadcn-svelte-get.ts and shadcn-svelte-list.tsnpm run dev to surface runtime integration issues earlyThis project is licensed under the MIT License - see the LICENSE file for details.
We welcome contributions! Please read our Contributing Guidelines and Code of Conduct before getting started.
For more details:
MCP_Prompts_System.md for comprehensive documentation on the MCP prompt systemMCP_ARCHITECTURE.md for detailed explanation of MCP server vs clientsrc/services/ for Crawlee-based real-time documentation fetching implementation.github/copilot-instructions.mdPlease log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.
{
"mcpServers": {
"shadcn-svelte": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp"
],
"env": {}
}
}
}claude mcp add shadcn-svelte npx -y mcp-remote https://shadcn-svelte.mastra.cloud/api/mcp/shadcn/mcp