v0-mcp

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:

Visit the v0 Model API documentation
Sign in to your Vercel account
Navigate to the API Keys section
Generate a new API key
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)

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

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

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)

Create or edit the Claude Code configuration file:
- macOS/Linux: ~/.claude.json
- Windows: %USERPROFILE%\.claude.json
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"
      }
    }
  }
}

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

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."

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

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:

Visit the v0 Model API documentation
Sign in to your Vercel account
Navigate to the API Keys section
Generate a new API key
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)

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

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

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)

Create or edit the Claude Code configuration file:
- macOS/Linux: ~/.claude.json
- Windows: %USERPROFILE%\.claude.json
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"
      }
    }
  }
}

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

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

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."

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

v0-mcp

v0-mcp

🎯 Features

🚀 Quick Start

🛠 Installation

1. Clone or Download

2. Install Dependencies

3. Setup Environment

4. Build Project

⚙️ Configuration

🔑 Getting Your v0 API Key

Claude Code Integration

Method 1: CLI Configuration (Recommended)

Method 2: Manual Configuration (Advanced)

Verification

🔗 Why Use MCP (Model Context Protocol)?

Claude Desktop Integration

Cursor Integration

🔧 Available Tools

v0_generate_ui

v0_generate_from_image

v0_chat_complete

v0_setup_check

🔑 Environment Variables

🚀 Usage Examples

In Claude Code

Direct v0-mcp Usage

Specific Tool Usage

Generate a Login Form

Convert Design to Code

Iterative Development

Check API Setup

Advanced Usage Examples

Creating a Dashboard Component

Building from a Wireframe

Iterative Refinement

🧪 Development

🛡️ Enhanced Features

Structured Logging

Advanced Error Handling

Testing Infrastructure

Improved Reliability

💖 Support This Project

📄 License

v0-mcp

🎯 Features

🚀 Quick Start

🛠 Installation

1. Clone or Download

2. Install Dependencies

3. Setup Environment

4. Build Project

⚙️ Configuration

🔑 Getting Your v0 API Key

Claude Code Integration

Method 1: CLI Configuration (Recommended)

Method 2: Manual Configuration (Advanced)

Verification

🔗 Why Use MCP (Model Context Protocol)?

Claude Desktop Integration

Cursor Integration

🔧 Available Tools

v0_generate_ui

v0_generate_from_image

v0_chat_complete

v0_setup_check

🔑 Environment Variables

🚀 Usage Examples

In Claude Code

Direct v0-mcp Usage

Specific Tool Usage

Generate a Login Form

Convert Design to Code

Iterative Development

Check API Setup

Advanced Usage Examples

Creating a Dashboard Component

Building from a Wireframe

Iterative Refinement

🧪 Development

`v0_generate_ui`

`v0_generate_from_image`

`v0_chat_complete`

`v0_setup_check`

`v0_generate_ui`

`v0_generate_from_image`

`v0_chat_complete`

`v0_setup_check`