v0-mcp

English | 中文

Vercel v0 MCP Server for Claude Code - Generate beautiful UI components using AI through the Model Context Protocol.

✨ Collaborative Development: This project was built through innovative collaboration between Claude Code and Gemini CLI using Vibe Coding methodology - demonstrating the power of AI-assisted development workflows.

🎯 Features

• Generate UI Components: Create React components from natural language descriptions
• Image to UI: Convert design images into working React code
• Chat-based Iteration: Iteratively refine components through conversation
• Multiple Models: Support for v0-1.5-md, v0-1.5-lg, and v0-1.0-md
• TypeScript Support: Full type safety with Zod schema validation
• Streaming Support: Real-time generation progress

🚀 Quick Start

# 1. Clone and enter the project
git clone <repository-url> && cd v0-mcp

# 2. Install dependencies
npm install

# 3. Create .env file and add your v0 API key
npm run setup
# Edit .env file with your V0_API_KEY

# 4. Build the project
npm run build

# 5. Add to Claude Code (ensure you are in the project root)
claude mcp add v0-mcp --env V0_API_KEY=$(grep V0_API_KEY .env | cut -d '=' -f2) -- node $(pwd)/dist/main.js

# 6. Start using it in Claude Code!
# Try: "Hey v0-mcp, create a login form with email and password fields"

🛠 Installation

1. Clone or Download

git clone <repository-url>
cd v0-mcp

2. Install Dependencies

npm install

3. Setup Environment

npm run setup
# Edit .env file with your v0 API key

4. Build Project

npm run build

⚙️ Configuration

🔑 Getting Your v0 API Key

Before configuring v0-mcp, you'll need a v0 API key:

1. Visit the v0 Model API documentation
2. Sign in to your Vercel account
3. Navigate to the API Keys section
4. Generate a new API key
5. Copy and save your key securely

Claude Code Integration

📖 Quick setup guide - choose the method that works best for you

Method 1: CLI Configuration (Recommended)

1. Add v0-mcp using the Claude Code CLI:

   # Navigate to your v0-mcp directory first
   cd /path/to/your/v0-mcp
   
   # Add the MCP server using current directory
   claude mcp add v0-mcp -- node $(pwd)/dist/main.js
   

2. Set your v0 API key:

   Option A: Add key during CLI setup

   # When adding the server, include the API key (run from v0-mcp directory)
   claude mcp add v0-mcp --env V0_API_KEY=your_v0_api_key_here -- node $(pwd)/dist/main.js
   

   Option B: Edit .claude.json file after setup

   After running the claude mcp add command, edit the generated .claude.json file:

   {
     "mcpServers": {
       "v0-mcp": {
         "type": "stdio",
         "command": "node",
         "args": ["/absolute/path/to/your/v0-mcp/dist/main.js"],
         "env": {
           "V0_API_KEY": "your_v0_api_key_here"
         }
       }
     }
   }
   

   Option C: System environment variable (Most secure)

   # Add to your shell profile (.bashrc, .zshrc, etc.)
   echo 'export V0_API_KEY="your_v0_api_key_here"' >> ~/.zshrc
   
   # Reload your shell configuration
   source ~/.zshrc
   

3. Verify your setup:

   claude mcp list
   node scripts/verify-claude-code-setup.js
   

   ✅ Expected Output:

   Verifying v0 API connection...
   ✓ v0-mcp server found in Claude configuration
   ✓ API key is configured
   ✓ Successfully connected to v0 API
   Setup is complete! You can now use v0-mcp in Claude Code.
   

Method 2: Manual Configuration (Advanced)

1. Create or edit the Claude Code configuration file:

   • macOS/Linux: ~/.claude.json
   • Windows: %USERPROFILE%\.claude.json

2. Add the v0-mcp server configuration:

{
  "mcpServers": {
    "v0-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/v0-mcp/dist/main.js"],
      "env": {
        "V0_API_KEY": "your_v0_api_key_here"
      }
    }
  }
}

3. Restart Claude Code for the changes to take effect.

Verification

After configuration, you should see v0-mcp tools available in Claude Code:

• ✅ v0_generate_ui - Generate UI components from text
• ✅ v0_generate_from_image - Generate UI from image references
• ✅ v0_chat_complete - Iterative UI development chat
• ✅ v0_setup_check - Verify API connectivity

🔗 Why Use MCP (Model Context Protocol)?

MCP Benefits:

• Seamless Integration: Tools appear natively in Claude without API juggling
• Enhanced Context: Claude understands your v0 workflow and provides better assistance
• Real-time Availability: Tools are always accessible during your coding sessions
• Type Safety: Full parameter validation and error handling built-in
• Persistent State: Maintains conversation context across tool calls

How It Works: When you mention v0-mcp or UI generation in Claude, the tools automatically become available. Claude can intelligently choose the right tool based on your request, making the development process feel natural and integrated.

Claude Desktop Integration

Add to your claude_desktop_config.json:

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

Cursor Integration

Add to your Cursor MCP configuration:

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

🔧 Available Tools

v0_generate_ui

Generate UI components from text descriptions.

Parameters:

• prompt (required): Description of the UI component
• model: v0 model to use (default: v0-1.5-md)
• stream: Enable streaming response (default: false)
• context: Optional existing code context

v0_generate_from_image

Generate UI components from image references.

Parameters:

• imageUrl (required): URL of the reference image
• prompt: Additional instructions
• model: v0 model to use (default: v0-1.5-md)

v0_chat_complete

Chat-based UI development with conversation context.

Parameters:

• messages (required): Array of conversation messages
• model: v0 model to use (default: v0-1.5-md)
• stream: Enable streaming response (default: false)

v0_setup_check

Validate v0 API configuration and connectivity.

🔑 Environment Variables

Variable	Required	Default	Description
V0_API_KEY	✅	-	Your v0 API key
V0_BASE_URL	❌	https://api.v0.dev/v1	v0 API base URL
V0_DEFAULT_MODEL	❌	v0-1.5-md	Default model to use
V0_TIMEOUT	❌	60000	API timeout (ms)
MCP_SERVER_NAME	❌	v0-mcp	MCP server name
LOG_LEVEL	❌	info	Logging level

🚀 Usage Examples

In Claude Code

Once configured, you can use v0-mcp in multiple ways:

Direct v0-mcp Usage

Simply mention v0-mcp in your request, and Claude will automatically select the appropriate tool:

Hey v0-mcp, create a modern login form with email and password fields

v0-mcp: Generate a dashboard component with charts and KPI cards

@v0-mcp convert this wireframe to a React component: [image URL]

Specific Tool Usage

Generate a Login Form

Use v0_generate_ui to create a modern login form with email, password fields, and a blue submit button with rounded corners.

Convert Design to Code

Use v0_generate_from_image with this Figma design URL: https://example.com/design.png

Iterative Development

Use v0_chat_complete to refine the previous login form by adding a "Remember me" checkbox and "Forgot password" link.

Check API Setup

Use v0_setup_check to verify your v0 API connection and configuration.

Advanced Usage Examples

Creating a Dashboard Component

Use v0_generate_ui with the following prompt:
"Create a modern dashboard component with a sidebar navigation, header with user profile dropdown, and a main content area with grid layout for cards. Include metrics cards showing KPIs with charts. Use shadcn/ui components and Tailwind CSS."

Building from a Wireframe

Use v0_generate_from_image with your wireframe image URL and add:
"Convert this wireframe into a fully functional React component. Add proper spacing, modern styling, and make it responsive for mobile devices."

Iterative Refinement

Use v0_chat_complete with conversation history:
[
  {"role": "user", "content": "Create a pricing table component"},
  {"role": "assistant", "content": "[Previous pricing table code]"},
  {"role": "user", "content": "Add a popular plan highlight and annual/monthly toggle"}
]

🧪 Development

# Development mode with hot reload
npm run dev

# Type checking
npm run lint

# Run tests
npm test

# Test with coverage
npm run test:coverage

# Test in CI mode
npm run test:ci

# Clean build artifacts
npm run clean

# Test configuration
npm run test:config

# Test basic functionality
npm run test:basic

# Verify Claude Code setup
npm run verify:claude-code

🛡️ Enhanced Features

Structured Logging

• Winston-based logging with JSON format
• Contextual information for API calls and tool usage
• Error tracking with stack traces and metadata
• Configurable log levels via LOG_LEVEL environment variable

Advanced Error Handling

• Categorized error types (API, Network, Timeout, Rate Limit, etc.)
• Retry logic with exponential backoff for transient errors
• User-friendly error messages with actionable guidance
• Comprehensive error metadata for debugging

Testing Infrastructure

• Jest testing framework with TypeScript support
• Comprehensive unit tests for all core components
• Test coverage reporting with configurable thresholds
• Mock implementations for external dependencies

Improved Reliability

• Input validation using Zod schemas
• Graceful error handling for all failure modes
• Performance monitoring with request timing
• Health checks for API connectivity

💖 Support This Project

If you find this project helpful, please consider supporting it:

Your support helps maintain and improve v0-mcp!

📄 License

MIT