EmbedUI MCP Server

这是一个用于 EmbedUI 后端 API 的 MCP (Model Context Protocol) 服务器，允许 Claude Code 客户端直接访问 EmbedUI 的功能。

功能特性

• 🔐 设备码认证 - 通过 EmbedUI Web 站点安全授权（类似微信设备登录）
• 📁 项目管理 - 列出、创建、删除项目
• 📄 文件操作 - 读取、写入、创建、删除、重命名文件
• 🌲 文件树浏览 - 查看项目目录结构
• ⚙️ 编译管理 - 提交编译任务、查看状态和日志
• 🤖 Worker 管理 - 启动、停止、查看 Worker 状态

安装

cd mcp-server
npm install

配置

方式 1: JWT Token（仅用于开发）

1. 复制环境变量示例文件：

cp .env.example .env

2. 编辑 .env 文件：

EMBEDUI_API_URL=https://www.embedui.com/api/v1
EMBEDUI_TOKEN=your_jwt_token_here

获取 JWT Token

通过 EmbedUI 的登录 API 获取：

curl -X POST https://www.embedui.com/api/v1/login \
  -H "Content-Type": "application/json" \
  -d '{"email":"[email protected]","password":"your_password"}'

从响应中复制 access_token 字段的值到 .env 文件。

方式 2: 设备码认证（推荐用于生产环境）

设备码认证无需额外配置，通过 EmbedUI Web 站点进行授权。使用时运行 device_auth 工具即可启动认证流程。

在 Claude Code 中配置

将以下配置添加到 Claude Code 的配置文件中：

配置文件位置

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

配置内容

{
  "mcpServers": {
    "embedui": {
      "command": "node",
      "args": ["./mcp-server/src/index.js"],
      "cwd": "/home/betwowt/project/embedui"
    }
  }
}

MCP 服务器会自动读取 mcp-server/.env 文件中的配置。

使用方法

• embedui_edit 的稳定使用方式见 EMBEDUI_EDIT_SKILL.md

使用设备码认证

首次使用时，需要先进行设备码认证：

你：启动 EmbedUI 设备认证

Claude：[调用 device_auth 工具]
========================================
EmbedUI MCP 设备认证
========================================

请在浏览器中访问以下 URL 进行授权：

http://your-embedui-url/mcp/authorize

输入授权码: ABC12345

========================================
授权完成后，等待自动获取 Token...
========================================

你：[在浏览器中完成授权]

Claude：[自动检测到授权完成]
========================================
认证成功！Token 已保存。
========================================

现在可以使用其他 EmbedUI 工具了。

你：列出我的所有项目

使用 Token 模式

如果已在 .env 文件中配置了 EMBEDUI_TOKEN，配置完成后直接在 Claude Code 中使用 EmbedUI 工具即可。

可用工具

认证工具

• device_auth - 启动设备码认证流程
• check_auth - 检查当前认证状态
• logout - 登出并清除 token

项目管理

• list_projects - 获取所有项目列表
• get_project - 获取指定项目的详细信息
• create_project - 创建新项目
• delete_project - 删除项目

文件操作

• get_file_tree - 获取项目的文件树结构
• read_file - 读取文件内容
• write_file - 写入文件内容
• create_file - 创建新文件
• create_folder - 创建文件夹
• delete_file - 删除文件或文件夹
• rename_file - 重命名文件或文件夹

编译管理

• compile_project - 提交编译任务
• get_compile_status - 获取编译任务状态
• get_compile_logs - 获取编译日志

Worker 管理

• list_workers - 获取项目的 Worker 列表
• get_worker_status - 获取 Worker 状态
• start_worker - 启动 Worker
• stop_worker - 停止 Worker

使用示例

在 Claude Code 中与 EmbedUI 交互

你：列出我所有的 EmbedUI 项目

Claude：[使用 list_projects 工具]
找到了以下项目：
1. 我的 LVGL 项目 (ID: xxx)
2. 演示项目 (ID: yyy)
...

你：读取"我的 LVGL 项目"中的 main.c 文件

Claude：[使用 get_file_tree 和 read_file 工具]
已读取 main.c 文件内容：
...

你：帮我在项目中创建一个新的按钮组件

Claude：[使用 write_file 工具]
已创建 button.c 和 button.h 文件...

你：编译这个项目

Claude：[使用 compile_project 工具]
编译任务已提交，任务 ID: task_xxx

你：查看编译状态

Claude：[使用 get_compile_status 工具]
编译已完成，状态: success

开发

# 开发模式（自动重启）
npm run dev

# 普通启动
npm start

故障排查

MCP 服务器无法连接

1. 检查 Claude Code 配置文件路径是否正确
2. 确认 Node.js 已安装：node --version
3. 查看 Claude Code 日志获取详细错误信息

设备码认证失败

1. 确认 EmbedUI 后端服务正在运行
2. 检查设备码是否已过期（15 分钟有效期）
3. 确认用户已在 EmbedUI 站点完成授权

API 认证失败

1. 确认 Token 是否正确
2. 检查 Token 是否过期（默认 24 小时）
3. 使用 check_auth 工具检查认证状态
4. 如果过期，使用 logout 后重新运行 device_auth

后端服务未启动

1. 确认 EmbedUI 后端服务正在运行
2. 检查 EMBEDUI_API_URL 是否正确
3. 测试 API 连接：curl https://www.embedui.com/api/v1/projects

安全建议

1. 不要将 .env 文件提交到版本控制
2. 生产环境使用设备码认证而不是硬编码 Token
3. 在生产环境使用 HTTPS
4. 定期更换 Token

Token 存储

Token 会自动保存在 mcp-server/src/.token.json 文件中，包含：

• Access Token
• Refresh Token（如果提供）
• 过期时间（如果提供）

Token 文件位置：

• 相对于 MCP 服务器脚本的目录
• 不会被 Git 跟踪（已在 .gitignore 中排除）