Shadcn Svelte Mcp

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

#mcp #mcp-server #shadcn #shadcn-svelte #svelte

shadcn-svelte-mcp

Mastra MCP server and tooling that provides real-time access to shadcn-svelte component documentation and developer utilities using web scraping. Now deployed and available at https://shadcn-svelte.mastra.cloud!

[!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.

🎉 What's New

✅ Production deployment on Mastra Cloud
✅ Three powerful MCP tools for component discovery and documentation
✅ 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
✅ Intelligent caching for performance
✅ Always up-to-date documentation

Installation in Your Code Editor

Add the Shadcn Svelte Docs MCP server to your AI code editor to get instant access to shadcn-svelte component documentation and utilities.

Cursor

Open Cursor Settings (Cmd/Ctrl + ,)
Navigate to "MCP" or "Model Context Protocol"
Add a new server configuration:

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

Or use the HTTP endpoint:

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

Windsurf

Open ~/.codeium/windsurf/mcp_config.json in your editor
Add the following configuration:

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

Save and restart Windsurf

Visual Studio Code

Create or edit .vscode/mcp.json in your workspace root
Add the server configuration:

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

Open VSCode settings and enable "Chat > MCP"
In Agent mode, open mcp.json and click "start"

Tip: You can also add MCP servers from the Command Palette in VS Code — press Ctrl+Shift+P (or Cmd+Shift+P on macOS), run "MCP: Add server" (or "mcp add server"), then choose:

"Command (stdio)" to run a local command that implements the MCP protocol (e.g., an npx command starting a stdio MCP server)
"HTTP (HTTP or Server-Sent Events)" to connect directly to a remote HTTP/SSE MCP endpoint (paste the https://.../mcp or .../sse URL)

This Command Palette flow is the quickest way to add a server without editing files manually.

Zed

Zed uses a settings.json file for MCP server configuration:

Open Zed settings (Cmd/Ctrl + ,)
Navigate to the JSON settings file (usually ~/.config/zed/settings.json)
Add the MCP server configuration 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": {}
    }
  }
}

Alternatively, for HTTP transport:

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

Save the file and restart Zed
Open the Agent Panel to verify the server is connected (look for a green indicator) Note: Zed also exposes a UI form for adding MCP/context servers which is often easier than editing settings.json manually — open Zed's Agent/AI settings and use the "Add server" form to paste the HTTP/SSE URL or configure a local command.

Claude Code CLI

Install using the terminal:

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

OpenAI Codex CLI

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

Then run codex mcp list to confirm it's enabled.

Available Tools

Once installed, your AI assistant will have access to these tools:

shadcnSvelteListTool - List all available shadcn-svelte components and documentation sections
shadcnSvelteGetTool - Get detailed documentation for a specific component (installation, usage, props, examples)
shadcnSvelteUtilityTool - Access installation guides, theming help, CLI usage, and migration assistance

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"
"How do I customize the theme for shadcn-svelte?"
"What are the props for the Dialog component?"
"Help me migrate from shadcn-svelte v0.x to v1.x"

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.
package.json - npm scripts and dependencies.

Quick start (development smoke-test)

Install dependencies (using your preferred package manager).

# npm
npm install

# or bun
bun install

# or pnpm
pnpm install

Set up environment variables for web scraping:

# Copy the example environment file
cp .env.example .env

# Add your Firecrawl API configuration
FIRECRAWL_API_URL=your_firecrawl_api_url
FIRECRAWL_API_KEY=your_firecrawl_api_key

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

Run MCP server locally (stdio):

npm run mcp:stdio

Or start the dev HTTP server:

npm run mcp:dev

Useful 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 mcp:stdio - Run the MCP server in stdio mode (runs npx tsx src/index.ts).
npm run mcp:dev - Run the MCP dev server (runs npx tsx src/dev-server.ts).
npm run test:firecrawl - Run the Firecrawl test harness (npx tsx src/test-firecrawl.ts)
npm run test:simple - Run the simple tools test (npx tsx src/test-tools-simple.ts)
npm run test:mcp - Run the MCP server test (npx tsx src/test-mcp.ts)
npm test - Placeholder test script (prints an error message by default)

MCP Architecture

This project exposes a production-ready MCP Server that makes shadcn-svelte documentation and tools available to AI code editors.

What this means:

MCP Server (src/mastra/mcp-server.ts) - Exposes three shadcn-svelte tools to external MCP clients (Cursor, Windsurf, VS Code, etc.)
No MCP Client needed - This project only provides tools, it doesn't consume tools from other servers

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.

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 Firecrawl API for real-time documentation fetching.
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: support@svelte-apps.me
Contributions: contrib@svelte-apps.me
Maintainer: Michael Obele (michael@svelte-apps.me)

For more details:

MCP Architecture: See MCP_ARCHITECTURE.md for detailed explanation of MCP server vs client
Web scraping services: See src/services/ for real-time documentation fetching implementation
AI assistant guide: See .github/copilot-instructions.md

Top categories

tailwind daisyui admin template popup mdsvex portfolio blog form ecommerce ui carousel auth dark seo image routing