Shadcn UI v4 MCP Server for Windsurf: Setup & Config

What you can do with Shadcn UI v4 in Windsurf

Match retrieved UI implementations to the framework and React primitives your project actually uses.

• Retrieve a larger UI block instead of assembling every screen element from isolated snippets.
• Inspect a TweakCN preset before asking the supplied theme operation to apply it.

Before you start: Shadcn UI v4 in Windsurf

• Node.js version 18 or above in the source-build prerequisites
• npm tooling for npx; npm or pnpm for source builds
• Client with MCP support

The basic npx command appears directly in the README. The GitHub environment entry is optional and documented separately. Initial defaults are React with Radix and stdio. Use --framework for another implementation; React can select Base UI with --ui-library base. Network examples use SSE or dual mode.

Shadcn UI v4 Windsurf configuration

1. Choose Windsurf configuration scope

   For Shadcn UI v4 MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Shadcn UI v4 MCP Server to Windsurf

   Use the shadcn-ui-mcp-unofficial entry below in mcpServers. Keep Shadcn UI v4 MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check Shadcn UI v4 MCP Server in Windsurf

   Shadcn UI v4 MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "shadcn-ui-mcp-unofficial": {
      "command": "npx",
      "args": [
        "@jpisnice/shadcn-ui-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<optional GitHub credential for a higher request allowance>"
      }
    }
  }
}

Shadcn UI v4 tools available to Windsurf

Shadcn UI v4's stored tool list documents 10 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

list_blocks

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for list_blocks.

get_block

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for get_block.

list_components

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for list_components.

get_component_metadata

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for get_component_metadata.

Look up a component's descriptive, dependency, and configuration information.

get_component_demo

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for get_component_demo.

Fetch usage-example code for the selected component.

get_component

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for get_component.

get_directory_structure

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for get_directory_structure.

list_themes

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for list_themes.

Browse the available TweakCN preset choices.

get_theme

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for get_theme.

Inspect the details behind one TweakCN preset.

apply_theme

After refreshing Shadcn UI v4 in Windsurf settings, check Cascade's tool list for apply_theme.

Use a chosen TweakCN preset to update the project's theme.

Shadcn UI v4: full stored tool descriptions

Troubleshooting Shadcn UI v4 in Windsurf

• Check npx @jpisnice/shadcn-ui-mcp-server (Node.js/npm) on the machine running Windsurf's MCP integration for Shadcn UI v4 MCP Server; refresh MCP and inspect Cascade's tools.
• Check GITHUB_PERSONAL_ACCESS_TOKEN for Shadcn UI v4 MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Shadcn UI v4 MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Omitting a GitHub token leaves the lower documented request allowance.
• Known limitation: Base UI is not an alternative for the non-React framework modes.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions