企业官网建设流程全解析

Figma Console MCP自托管部署完全指南：Cloudflare Workers+OAuth 2.0+Durable Object企业级配置

【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcp

Figma Console MCP 是一款面向设计系统的 MCP 服务器，可将 AI 助手接入 Figma，完成设计令牌提取、组件创建、变量管理与无障碍审计。自托管部署让你在自己的 Cloudflare Workers 上运行它，用OAuth 2.0实现按用户授权，用Durable Object维持持久会话——数据完全自主可控，是团队与企业接入 Figma 的稳妥方案。

为什么选择自托管部署？

官方提供的公共实例适合大多数个人用户，但以下场景更适合部署自己的实例：

官方文档中对自托管的说明见 docs/self-hosting.md。

1 分钟看懂自托管部署架构

整个部署由四类 Cloudflare 组件协作完成，配置都集中在 wrangler.jsonc 中：

AI 客户端 → Cloudflare Worker（入口） ├─→ REST 客户端 → Figma API（读取设计数据） ├─→ MCP 会话 Durable Object（持久化 MCP 会话） ├─→ Plugin Relay Durable Object（云写中继） │ └─ WebSocket → Desktop Bridge 插件 → Figma └─→ KV 命名空间（OAuth Token / OAuth State 存储）

• Cloudflare Worker：服务入口，主逻辑位于 src/index.ts
• 两个 Durable Object：MCP_OBJECT负责保持每个用户的 MCP 会话长连接；PLUGIN_RELAY（即 src/cloud-websocket-relay.ts）负责把网页端 AI 的写操作经 WebSocket 中继到 Figma 桌面端插件
• 两个 KV 命名空间：OAUTH_TOKENS加密存储每位用户的 Figma 令牌，OAUTH_STATE防重放攻击的授权状态
• Browser Rendering 绑定：支撑云端模式的控制台日志、截图、页面导航工具

💡 详细的数据流图与组件职责，可参考 docs/architecture.md。

部署前准备：三样东西缺一不可

✅Cloudflare 账户（免费版即可起步） ✅Wrangler CLI（npm install后自动可用，是 Cloudflare 的部署工具） ✅Figma OAuth 应用：在 Figma 开发者平台创建一个 App，用于后面配置 OAuth 2.0 按用户授权

另外注意：云端模式的浏览器渲染工具（截图、看控制台）依赖 Cloudflare 的 Browser Rendering API，免费额度为每天 10 分钟、3 个并发浏览器，超出后按每浏览器小时计费——个人使用基本零成本。

快速部署到 Cloudflare Workers：4 步上线

第 1 步：克隆并安装

git clone https://gitcode.com/gh_mirrors/fi/figma-console-mcp cd figma-console-mcp npm install

第 2 步：登录 Wrangler

npx wrangler login

浏览器会打开 Cloudflare 授权页，确认后回到终端即完成认证。

第 3 步：配置密钥

企业部署推荐用 OAuth 2.0 按用户认证（下一步详述），两个密钥都要设置：

npx wrangler secret put FIGMA_OAUTH_CLIENT_ID npx wrangler secret put FIGMA_OAUTH_CLIENT_SECRET

常用可选配置：

第 4 步：构建并部署

npm run build:cloudflare npm run deploy

看到Deployment complete!后，会得到一个形如https://figma-console-mcp.<你的子域名>.workers.dev的专属端点。

OAuth 2.0 认证配置：告别共享 Token

自托管的最大优势之一是OAuth 2.0 按用户认证：每位团队成员用自己的 Figma 账户授权，令牌加密存储在 Workers KV 中，按会话隔离，90 天自动过期清理——彻底避免"大家共用一个个人访问令牌"的安全隐患。

管理员只需 3 步：

1. 创建 Figma OAuth 应用：在 Figma 开发者平台进入 "My Apps → Create new app"，名称可填Figma Console MCP
2. 配置重定向 URL：填写你的部署地址加/oauth/callback，例如https://mcp.example.com/oauth/callback，务必与最终部署 URL 完全一致
3. 将 Client ID 和 Client Secret 设为 Wrangler 密钥（即上文的FIGMA_OAUTH_CLIENT_ID/FIGMA_OAUTH_CLIENT_SECRET）

完成后用健康检查接口验证：

curl https://你的域名/health

返回中"oauth_configured": true即表示 OAuth 配置生效。

终端用户的体验则完全无感：第一次调用 Figma 工具时浏览器自动弹出授权页 → 登录并点击允许 → 后续所有 API 调用自动使用个人令牌，过期自动刷新。完整的认证流程与故障排查见 docs/oauth-setup.md。

Durable Object：云写中继如何维持连接

传统 MCP 请求是无状态的，但 Figma 的写操作需要一条"活的"通道。PluginRelayDO这个 Durable Object 就是答案：它把网页端 AI 客户端（如 Claude.ai）的写命令，经 WebSocket 实时中继到你 Figma Desktop 里的 figma-desktop-bridge/ 插件，由插件调用 Figma Plugin API 执行后原路返回结果。

AI 客户端 → 云 MCP 服务器 → Durable Object 中继 → Desktop Bridge 插件 → Figma

配对方式很简单：让 AI 说一句"Connect to my Figma plugin"，它会给出一个 6 位配对码（5 分钟有效），在插件界面开启 "Cloud Mode"、输入配对码点击 Connect 即可，云端即可获得 96 个工具（含完整写权限）。

验证部署并接入 AI 客户端

部署成功后，把 MCP 客户端指向你的专属端点即可。以 Claude 桌面端为例，在 MCP 配置文件中添加：

{ "mcpServers": { "figma-console": { "command": "npx", "args": ["mcp-remote", "https://你的域名/sse"] } } }

下图是一个典型 MCP 客户端的服务器配置界面，自托管后只需把端点地址换成你自己的 Workers 域名：

Claude Code 用户可以用一条命令完成接入：

claude mcp add figma-console -- npx -y mcp-remote@latest https://你的域名/sse

📌小贴士：/sse端点适合 Claude Desktop / Claude Code；/mcp端点适合网页端 AI 客户端（搭配配对码走 OAuth/Bearer 认证）。各端点能力差异对照见 docs/mode-comparison.md。

监控、成本与回滚

实时日志：npx wrangler tail可跟随生产日志，加--status error只看错误。

成本估算（Workers 免费层每天 10 万请求，付费层 5 美元/月含 Durable Objects + KV）：

版本管理：更新走git pull → npm install → npm run build:cloudflare → npm run deploy；出问题可用npx wrangler rollback一键回滚，npx wrangler deployments list查看历史版本。

企业级安全最佳实践

• 🔒密钥管理：只通过wrangler secret put设置（静态加密），绝不提交到代码仓库，也不写进 wrangler.jsonc
• 🔑令牌最小权限：OAuth 应用只申请file_content:read、library_content:read、file_variables:read等必要作用域
• 🚦限流防护：在 Cloudflare 仪表盘的 Security → WAF 中为 Worker 路由添加按 IP 限流规则
• 🧱访问控制：进阶可加 API Key 校验中间件，配合npx wrangler secret put API_KEY使用

部署失败、OAuth 报错、成本偏高等常见问题，官方已整理好排查清单，见 docs/troubleshooting.md。

小结

按本指南走完，你就拥有了一个数据自主、按用户授权、带持久会话的企业级 Figma MCP 实例——AI 助手从此能安全地"读懂"并"改写"你的设计系统。

【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcp