快速开始

无需克隆，无需构建。 从 npm 安装 tunnel 和 MCP server，从 GitHub 获取插件，即可连接。

想要完全掌控源码？请参阅克隆构建指南。

前提条件

Node.js (v18+)
Figma 桌面版或网页版
支持 MCP 的 AI 编程工具（Claude Code、Cursor、Windsurf 等）

模型	提供商
Claude Opus 4.6	Anthropic（Claude Code、Cursor 等）
GPT-5.3-Codex	OpenAI（ChatGPT Codex）
Gemini 3.1 Pro	Google（Gemini CLI、Cursor 等）

1. 下载 Figma 插件

从 GitHub Releases 下载最新的 vibma-plugin 压缩包——包含 manifest.json、code.js 和 ui.html。

解压即可。

2. 启动 WebSocket tunnel

npx @ufira/vibma-tunnel

你应该会看到：WebSocket server running on port 3055

关于端口

Vibma 默认使用端口 3055。Figma 插件白名单中包含端口 3055–3058，如果 3055 已被占用，可以使用其他端口。使用其他端口的方法：

VIBMA_PORT=3056 npx @ufira/vibma-tunnel

在 Figma 插件界面中点击 Connect 前，请先更新端口字段使其匹配。

3. 安装 Figma 插件

在 Figma 中，前往 Plugins > Development > Import plugin from manifest…
选择解压后插件文件夹中的 manifest.json
运行插件——将显示连接面板

4. 在 AI 工具中配置 MCP

添加到你的 MCP 配置文件（例如 .cursor/mcp.json、.claude.json 或 .mcp.json）：

{
  "mcpServers": {
    "Vibma": {
      "command": "npx",
      "args": ["-y", "@ufira/vibma@latest", "--edit"]
    }
  }
}

访问层级

Vibma 通过访问层级控制可用工具。通过传入标志设置层级：

标志	访问层级	可用工具	使用场景
(无)	read	检查、搜索、导出	安全浏览、审查
`--create`	read create	只读 + 创建工具，例如 frame、文本和形状	生成新设计
`--edit`	read create edit	完整工具权限，包括编辑和删除操作	完整设计工作流

大多数用户需要 --edit 以获得完整权限。省略标志则为只读模式。

非默认端口

如果使用非默认端口，添加 --port=：

{
  "mcpServers": {
    "Vibma": {
      "command": "npx",
      "args": ["-y", "@ufira/vibma@latest", "--edit", "--port=3056"]
    }
  }
}

可选：库与图片 API 密钥

Vibma 的核心工具无需任何 API 密钥。如需启用团队库发现和图库照片搜索，请在 MCP 配置中添加环境变量：

{
  "mcpServers": {
    "Vibma": {
      "command": "npx",
      "args": ["-y", "@ufira/vibma@latest", "--edit"],
      "env": {
        "FIGMA_API_TOKEN": "<your-figma-pat>",
        "FIGMA_TEAM_ID": "<your-team-id>",
        "PEXELS_API_KEY": "<your-pexels-key>"
      }
    }
  }
}

获取 Figma 个人访问令牌

前往 Figma 设置 > 安全，滚动到 Personal access tokens
点击 Generate new token，勾选以下两个权限：
- File content — Read（file_content:read）
- Team library content — Read（team_library_content:read）
复制生成的令牌 — 以 figd_ 开头

获取 Team ID

Team ID 是 Figma 主页 URL 中的数字：

https://www.figma.com/files/team/1234567890/...
                                 ^^^^^^^^^^
                                 这就是你的 TEAM_ID

URL 中的 Team ID

获取 Pexels API 密钥

前往 pexels.com/api/key 注册或登录
申请 API 密钥 — 个人和商业用途均免费
从控制面板复制密钥

Pexels 照片可免费使用，包括商业用途。请阅读 Pexels 服务条款，在生产环境中使用图片时请注明摄影师。Vibma 会自动将摄影师信息附加到放置的图片节点描述中。

5. 连接

在 Figma 插件中，将频道名设置为 vibma（或任意你喜欢的名称）
点击 Connect
在 AI 工具中调用 connection(method: "create")，使用相同的频道名（默认为 vibma）
调用 connection(method: "get") ——你应该会收到包含文档名称的 pong 响应

更新

npx 会缓存已安装的包，因此你可能不会自动获取最新版本。更新方法：

MCP server 和 tunnel — 使用 @latest 标签：

npx @ufira/vibma-tunnel@latest

{
  "mcpServers": {
    "Vibma": {
      "command": "npx",
      "args": ["-y", "@ufira/vibma@latest", "--edit"]
    }
  }
}

或清除 npx 缓存以强制下次重新下载：

npx clear-npx-cache

Figma 插件 — 从 GitHub Releases 下载最新的 vibma-plugin.zip，解压后在 Figma 中重新导入 manifest.json。

故障排除

插件无法连接 WebSocket：确保 tunnel 正在运行。插件默认连接到 ws://localhost:3055。

MCP 显示断开连接：更改 MCP 配置后重启你的 AI 工具。基于 stdio 的 MCP server 无法热重载。

端口已被占用：终止现有进程（lsof -ti:3055 | xargs kill）或使用下一个可用端口（3056–3058）。