v0-mcp-bridge

Name: v0-mcp-bridge
Availability: InStock
Author: Edwin Anderson

No description

GitHub

GitHub Stars

User Rating

Not Rated

Forks

Issues

Views

Favorites

README

v0 MCP Server

Designed by Edwin Anderson

A production-ready Model Context Protocol (MCP) server that bridges the gap between AI development tools and v0.dev's superior UI generation capabilities. This server enables any MCP-compatible application (Claude Desktop, Claude Code, or custom implementations) to leverage v0.dev's specialized expertise in React/Next.js component generation, creating beautiful and modern UI designs with ease.

🎯 Project Vision

This MCP server creates perfect synergy between AI development tools and v0.dev's specialized UI generation:

v0.dev handles: Beautiful UI components, modern design patterns, shadcn/ui integration, responsive layouts
Your AI tool handles: Project structure, file organization, state management, API integration, testing, and overall development workflow

The result is the best of both worlds: stunning UI components seamlessly integrated into well-architected applications, accessible from any MCP-compatible environment.

🎉 All Phases Complete ✅

Current Status: Phase 4 Complete - Production ready with comprehensive features

✨ Key Features

8 Comprehensive Tools: Complete workflow from analysis to advanced generation
22 UI Templates: Pre-built patterns across 6 categories (forms, cards, navigation, layouts, data-display, modals)
Multimodal Support: Generate components from wireframes, designs, and screenshots
Enhanced Error Handling: Descriptive error messages and robust validation
Type Safety: Full TypeScript coverage with comprehensive Zod validation
Production Ready: Optimized code, cleanup, and enhanced documentation

🛠️ Available Tools

Foundation Tools:

test_connection - Test v0.dev API connectivity with detailed diagnostics
configure_v0 - Configure and validate API settings

Core Generation Tools:

analyze_requirements - Break down UI requirements into component structure (UI decomposition only)
generate_component - Generate React/Next.js components with shadcn/ui + Tailwind
improve_component - Enhance existing components with targeted improvements

Advanced Features:

generate_from_image - Generate components from wireframes/designs/screenshots (multimodal)
generate_from_template - Create components using 22 pre-built UI pattern templates
list_templates - Browse available templates by category (forms, cards, navigation, layouts, data-display, modals)

🚀 Quick Start

Prerequisites

Node.js 18+
v0.dev API key (get one here)
An MCP-compatible application (Claude Desktop, Claude Code, or custom implementation)

Installation

Choose your preferred installation method:

Option 1: Direct from GitHub (Recommended)

No cloning or building required! Use npx to run directly from GitHub:

Configure in your MCP client:

For Claude Desktop: Add to your MCP settings:

{
  "mcpServers": {
    "v0-mcp": {
      "command": "npx",
      "args": ["--yes", "github:edwin-anderson/v0-mcp-bridge"],
      "env": {
        "V0_API_KEY": "your_v0_api_key"
      }
    }
  }
}

For Claude Code (Recommended - Project Level):

claude mcp add v0-mcp -e V0_API_KEY=your_v0_api_key -- npx --yes github:edwin-anderson/v0-mcp-bridge

For Claude Code (User Level):

claude mcp add v0-mcp -s user -e V0_API_KEY=your_v0_api_key -- npx --yes github:edwin-anderson/v0-mcp-bridge

💡 Tip: We recommend project-level installation (without -s user) so you have better control and visibility over which projects use the v0 MCP server.

For custom MCP implementations: Use the standard MCP stdio transport to launch the server via npx.

That's it! Your MCP client will automatically download and run the latest version.

Option 2: Local Development Setup

For local development or customization:

Clone and install dependencies:

git clone https://github.com/edwin-anderson/v0-mcp-bridge.git
cd v0-mcp-bridge
npm install

Configure environment:

cp .env.example .env
# Edit .env and add: V0_API_KEY=your_v0_api_key_here

Build and test:
```
npm run build
npm run typecheck
```

Configure in your MCP client:

{
  "mcpServers": {
    "v0-mcp": {
      "command": "/path/to/node",
      "args": ["/path/to/v0-mcp-bridge/dist/index.js"],
      "env": {
        "V0_API_KEY": "your_v0_api_key"
      }
    }
  }
}

📋 Available Commands

npm run build - Build TypeScript to JavaScript (required before using with Claude Code)
npm run dev - Development with hot reload
npm run typecheck - TypeScript type checking
npm start - Run the built server
npx fastmcp dev src/index.ts - Test server standalone
npx fastmcp inspect src/index.ts - Inspect available tools

🎨 Template Library (22 Templates)

Forms (6)

login-form, contact-form, signup-form, checkout-form, search-form, settings-form

Cards (3)

product-card, user-profile-card, pricing-card

Navigation (2)

header-nav, sidebar-nav

Layouts (6)

dashboard-grid, hero-section, auth-layout, landing-page, profile-layout, error-page

Data Display (2)

data-table, stats-grid

Modals (3)

confirmation-dialog, image-gallery, drawer-panel

Each template includes multiple variants and customization options.

🔧 Usage Examples

Basic Component Generation

// Your MCP client will use:
generate_component({
  name: "UserCard",
  description: "Display user information with avatar and details",
  framework: "nextjs",
  responsive: true,
  accessibility: true,
});

Template-Based Generation

// Generate from template:
generate_from_template({
  name: "ContactForm",
  template: "contact-form",
  variant: "with-validation",
  customizations: ["Add phone field", "Custom submit text"],
});

Multimodal Generation

// Generate from wireframe:
generate_from_image({
  name: "Dashboard",
  images: [{ data: "base64...", type: "wireframe" }],
  description: "Admin dashboard layout",
});

🏗️ Architecture

src/
├── client/           # V0 API client with enhanced error handling
├── server/          # FastMCP server with 8 tools
├── services/        # Templates and prompt management
├── types/           # TypeScript definitions and Zod schemas
├── utils/           # Configuration, logging, and utilities
└── index.ts         # Main entry point with graceful shutdown

plan-and-documentation/  # Comprehensive project docs
├── CLAUDE_MD_RULES.md   # Claude Code integration rules
├── TASK_TRACKER.md      # Phase completion tracking
└── ...                  # Additional documentation

🔒 Environment Variables

V0_API_KEY - Your v0.dev API key (required)
- Get from v0.dev
- Used for component generation API calls
- Costs managed by your own v0.dev account

📚 Documentation

CLAUDE_MD_RULES.md - Complete integration guide for Claude Code
TASK_TRACKER.md - Implementation progress and technical decisions
API_REFERENCE.md - Detailed API documentation

🎯 Key Design Principles

Universal Compatibility: Works with any MCP-compatible client (Claude Desktop, Claude Code, custom implementations)
Clear Boundaries: v0 handles UI generation, your AI tool handles project structure
Type Safety: Full TypeScript coverage with runtime validation
Error Recovery: Comprehensive error handling with actionable messages
Template-Driven: 22 pre-built patterns for rapid development
Multimodal: Support for wireframes, designs, and screenshots
Production Ready: Optimized, tested, and documented

⚠️ Important Notes

Build Required: Run npm run build after code changes before testing with Claude Code
API Costs: v0.dev API usage is charged to your account - use wisely
Model: Uses v0-1.5-md model (not v0-preview)
Stdio Transport: Configured for Claude Code MCP integration
No Console Logging: MCP-safe logging to avoid JSON-RPC conflicts