v0-MCP服务器

Name: v0-MCP服务器
Author: hellolucky

作者：hellolucky11 星标更新：2025-06-26

安装使用来源：spider==github.com

项目介绍

v0-mcp

Vercel v0 MCP Server for Claude Code - 使用模型上下文协议通过AI生成漂亮的UI组件。 | 中文

✨ 协作开发: 该项目通过Claude Code和Gemini CLI之间的创新合作，采用Vibe编码方法构建——展示了AI辅助开发工作流程的强大之处。

🎯 特性

生成UI组件: 从自然语言描述创建React组件
图像转UI: 将设计图像转换为可工作的React代码
基于聊天的迭代: 通过对话迭代地改进组件
多种模型支持: 支持v0-1.5-md, v0-1.5-lg, 和 v0-1.0-md
TypeScript支持: 使用Zod模式验证实现完全类型安全
流式支持: 实时生成进度

🚀 快速开始

# 1. 克隆并进入项目
git clone <repository-url> && cd v0-mcp

# 2. 安装依赖
npm install

# 3. 创建.env文件并添加你的v0 API密钥
npm run setup
# 编辑.env文件，添加你的V0_API_KEY

# 4. 构建项目
npm run build

# 5. 添加到Claude Code（确保你在项目根目录）
claude mcp add v0-mcp --env V0_API_KEY=$(grep V0_API_KEY .env | cut -d '=' -f2) -- node $(pwd)/dist/main.js

# 6. 开始在Claude Code中使用它！
# 尝试："嘿v0-mcp，创建一个带有电子邮件和密码字段的登录表单"

🛠 安装

1. 克隆或下载

git clone <repository-url>
cd v0-mcp

2. 安装依赖

npm install

3. 设置环境

npm run setup
# 编辑.env文件，添加你的v0 API密钥

4. 构建项目

npm run build

⚙️ 配置

🔑 获取你的v0 API密钥

在配置v0-mcp之前，你需要一个v0 API密钥：

访问v0 模型API文档
登录到你的Vercel账户
导航到API密钥部分
生成一个新的API密钥
复制并安全保存你的密钥

Claude Code集成

📖 快速设置指南 - 选择最适合你的方法

方法1：CLI配置（推荐）

使用Claude Code CLI添加v0-mcp:

# 首先导航到你的v0-mcp目录
cd /path/to/your/v0-mcp

# 使用当前目录添加MCP服务器
claude mcp add v0-mcp -- node $(pwd)/dist/main.js

设置你的v0 API密钥:

选项A：在CLI设置期间添加密钥

# 在添加服务器时包括API密钥（从v0-mcp目录运行）
claude mcp add v0-mcp --env V0_API_KEY=your_v0_api_key_here -- node $(pwd)/dist/main.js

选项B：设置后编辑.claude.json文件

运行claude mcp add命令后，编辑生成的.claude.json文件：

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

选项C：系统环境变量（最安全）

# 添加到你的shell配置文件（.bashrc, .zshrc等）
echo 'export V0_API_KEY="your_v0_api_key_here"' >> ~/.zshrc

# 重新加载你的shell配置
source ~/.zshrc

验证你的设置:

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

✅ 预期输出:

验证v0 API连接...
✓ v0-mcp服务器在Claude配置中找到
✓ API密钥已配置
✓ 成功连接到v0 API
设置完成！你现在可以在Claude Code中使用v0-mcp。

方法2：手动配置（高级）

创建或编辑Claude Code配置文件:
- macOS/Linux: ~/.claude.json
- Windows: %USERPROFILE%\.claude.json
添加v0-mcp服务器配置:

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

重启Claude Code 以使更改生效。

验证

配置后，你应该能在Claude Code中看到可用的v0-mcp工具：

✅ v0_generate_ui - 从文本生成UI组件
✅ v0_generate_from_image - 从图像参考生成UI
✅ v0_chat_complete - 基于对话的UI开发迭代
✅ v0_setup_check - 验证API连接

🔗 为什么使用MCP（模型上下文协议）？

MCP优势:

无缝集成: 工具在Claude中像本地一样出现，无需处理API
增强的上下文: Claude理解你的v0工作流程，并提供更好的帮助
实时可用性: 工具在你的编码会话中始终可用
类型安全: 内置完整的参数验证和错误处理
持久状态: 维护跨工具调用的对话上下文

如何工作: 当你在Claude中提到v0-mcp或UI生成时，工具会自动变得可用。Claude可以根据你的请求智能选择合适的工具，使开发过程感觉自然且集成。

Claude桌面集成

添加到你的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集成

添加到你的Cursor MCP配置:

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

🔧 可用工具

`v0_generate_ui`

从文本描述生成UI组件。

参数:

prompt (必需): UI组件的描述
model: 要使用的v0模型（默认: v0-1.5-md）
stream: 启用流式响应（默认: false）
context: 可选的现有代码上下文

`v0_generate_from_image`

从图像参考生成UI组件。

参数:

imageUrl (必需): 参考图像的URL
prompt: 额外指令
model: 要使用的v0模型（默认: v0-1.5-md）

`v0_chat_complete`

基于对话的UI开发，具有对话上下文。

参数:

messages (必需): 对话消息数组
model: 要使用的v0模型（默认: v0-1.5-md）
stream: 启用流式响应（默认: false）

`v0_setup_check`

验证v0 API配置和连接。

🔑 环境变量

变量	必需	默认值	描述
`V0_API_KEY`	✅	-	你的v0 API密钥
`V0_BASE_URL`	❌	`https://api.v0.dev/v1`	v0 API基础URL
`V0_DEFAULT_MODEL`	❌	`v0-1.5-md`	要使用的默认模型
`V0_TIMEOUT`	❌	`60000`	API超时（毫秒）
`MCP_SERVER_NAME`	❌	`v0-mcp`	MCP服务器名称
`LOG_LEVEL`	❌	`info`	日志级别

🚀 使用示例

在Claude Code中

配置完成后，你可以以多种方式使用v0-mcp:

直接使用v0-mcp

只需在请求中提及v0-mcp，Claude将自动选择适当的工具:

嘿v0-mcp，创建一个带有电子邮件和密码字段的现代登录表单

v0-mcp: 生成一个带有图表和KPI卡片的仪表板组件

@v0-mcp 将这个线框图转换为React组件: [图像URL]

具体工具使用

生成登录表单

使用v0_generate_ui创建一个带有电子邮件、密码字段和圆角蓝色提交按钮的现代登录表单。

设计转代码

使用v0_generate_from_image和这个Figma设计URL: https://example.com/design.png

迭代开发

使用v0_chat_complete来改进之前的登录表单，添加“记住我”复选框和“忘记密码”链接。

检查API设置

使用v0_setup_check来验证你的v0 API连接和配置。

高级使用示例

创建仪表板组件

使用v0_generate_ui和以下提示:
"创建一个带有侧边栏导航、带有用户资料下拉菜单的页眉以及用于卡片的网格布局的主要内容区域的现代仪表板组件。包括显示KPI的带有图表的指标卡片。使用shadcn/ui组件和Tailwind CSS。"

从线框图构建

使用v0_generate_from_image和你的线框图图像URL，并添加:
"将这个线框图转换为一个完全功能的React组件。添加适当的间距、现代样式，并使其对移动设备响应。"

迭代改进

使用v0_chat_complete和对话历史记录:
[
  {"role": "user", "content": "创建一个定价表组件"},
  {"role": "assistant", "content": "[之前的定价表代码]"},
  {"role": "user", "content": "添加一个突出的热门计划和年/月切换"}
]

🧪 开发

# 开发模式带热重载
npm run dev

# 类型检查
npm run lint

# 运行测试
npm test

# 测试覆盖率
npm run test:coverage

# CI模式测试
npm run test:ci

# 清理构建工件
npm run clean

# 测试配置
npm run test:config

# 测试基本功能
npm run test:basic

# 验证Claude Code设置
npm run verify:claude-code

🛡️ 增强功能

结构化日志

基于Winston的日志，采用JSON格式
API调用和工具使用的上下文信息
带有堆栈跟踪和元数据的错误追踪
通过LOG_LEVEL环境变量配置的日志级别

高级错误处理

分类错误类型（API、网络、超时、速率限制等）
瞬时错误的指数退避重试逻辑
带有操作指导的用户友好错误消息
全面的错误元数据用于调试

测试基础设施

支持TypeScript的Jest测试框架
所有核心组件的综合单元测试
可配置阈值的测试覆盖率报告
外部依赖项的模拟实现

提高可靠性

使用Zod模式进行输入验证
所有故障模式的优雅错误处理
带有请求时间监控的性能监控
API连接的健康检查

💖 支持此项目

如果你发现这个项目有用，请考虑支持它：

你的支持有助于维护和改进v0-mcp！

📄 许可

MIT