--- title: "配置 flare.design MCP" description: "把 MCP 客户端连接到 flare.design，用来读取项目、查看实时画布状态、放置媒体、创建 AI 任务，并执行受控编辑。" locale: "zh" section: "MCP" updated: "2026-06-22" source: "https://flare.design/zh/docs/configure-flare-design-mcp" --- # 配置 flare.design MCP 把 MCP 客户端连接到 flare.design，用来读取项目、查看实时画布状态、放置媒体、创建 AI 任务，并执行受控编辑。 > 分类: MCP [HTML](https://flare.design/zh/docs/configure-flare-design-mcp) | [Markdown](https://flare.design/zh/docs/configure-flare-design-mcp/index.md) flare.design 提供远程 MCP endpoint，适合支持 OAuth 和 protected resource 的 MCP 客户端接入。接入后，客户端可以读取项目上下文、放置媒体、创建 AI 生成和云端渲染任务，也可以对协作画布执行受控编辑。 ## Endpoint 在 MCP 客户端里使用这个 endpoint： ```json { "mcpServers": { "flare-design": { "url": "https://mcp.flare.design/mcp" } } } ``` ## 推荐安装 Flare Skill 如果使用 Codex、Claude Code 或其他支持 skill 的本地 agent，建议安装 Flare Skill，让 agent 按照 Flare 推荐的画布、资产、动效和生成媒体流程操作： ```bash npx skills add flare-design/flare-skill --skill flare --global ``` 如果需要走内部或私有 SSH 仓库： ```bash npx skills add git@github.com:flare-design/flare-skill.git --skill flare --global ``` 如果想同时安装到 Codex 和 Claude Code： ```bash npx skills add git@github.com:flare-design/flare-skill.git --skill flare --agent codex claude-code --global ``` 保持已安装 skill 为最新版本： ```bash npx skills check npx skills update flare ``` MCP 的 `check_client_setup` 工具会让 agent 在可见画布写入前，对比本地已安装 skill 版本和服务端推荐版本。如果有新版本，agent 会提醒你运行 `npx skills update flare`，避免继续使用过期说明。 Skill 只是给 agent 的操作说明。目标客户端仍然需要单独配置上面的 MCP endpoint。 ## 授权 MCP server 是 protected resource。客户端应发起 OAuth 流程，引导你登录 flare.design，并请求它需要的 scope。 Flare 授权页会把 MCP 请求的 scope 展示成可选择权限。Agent 推荐权限默认勾选：`projects:read`、`canvas:read`、`canvas:write`、`assets:read`、`assets:write`。Flare 后端生成和云端渲染权限会单独展示，默认不勾选，因为创建生成或渲染任务可能消耗 Flares、渲染额度或套餐用量。 常用 scope： - `projects:read` 用于列出和读取项目 metadata。 - `canvas:read` 用于通过 `get_canvas_snapshot`、`get_live_canvas_context`、`get_image_annotation_context`、`export_project_snapshot` 读取画布快照、实时上下文和图片批注上下文。 - `canvas:write` 用于通过 `apply_canvas_patch`、`insert_text`、`insert_rect`、`create_frame`、`insert_html`、`update_text`、`set_layer_style`、`reorder_nodes`、`group_nodes`、`delete_nodes`、`add_audio_track`、`add_caption_track`、`apply_motion_design` 等工具执行画布、时间线和动效编辑。 - `assets:read` 用于列出账号资产，并通过 `insert_asset_image` 或 `insert_asset_video` 把已有媒体放入画布。 - `assets:write` 用于通过 `create_image_upload_session` 或 `get_image_upload_endpoint` 创建短时二进制上传会话，通过 `save_image_asset_from_url` 保存公开 HTTPS 图片，并通过 `insert_agent_generated_image`、`insert_generated_image` 或 `insert_asset_image` 放置 agent 提供的图片。 - `generation:read` 和 `generation:create` 用于查询或创建 Flare AI 生成任务。 - `render:read` 和 `render:create` 用于查询或创建云端渲染任务。 只把写权限授权给你信任的客户端。如果只是做分析、总结或读取画布，读权限通常就够了。只有在你希望 agent 启动 Flare 后端任务时，才勾选 `generation:create` 或 `render:create`。 ## 工具分组 | 需求 | 工具 | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 客户端设置 | `check_client_setup` | | 项目和画布上下文 | `list_projects`、`get_project`、`get_canvas_snapshot`、`get_live_canvas_context`、`get_image_annotation_context`、`export_project_snapshot` | | 能力查询 | `list_generation_models`、`list_motion_presets`、`list_shader_presets`、`list_canvas_patch_operations`、`list_media_capabilities`、`list_render_presets` | | 账号资产和媒体放置 | `list_assets`、`create_image_upload_session`、`get_image_upload_endpoint`、`save_image_asset_from_url`、`insert_agent_generated_image`、`insert_generated_image`、`insert_codex_generated_image`、`insert_asset_image`、`insert_asset_video` | | 画布创建和编辑 | `apply_canvas_patch`、`insert_text`、`insert_rect`、`create_frame`、`insert_html`、`update_text`、`set_layer_style`、`reorder_nodes`、`group_nodes`、`delete_nodes` | | 时间线和动效 | `add_audio_track`、`add_caption_track`、`apply_motion_design` | | AI 生成和云端渲染 | `create_generation_job`、`get_generation_job`、`list_generation_jobs`、`create_render_job`、`get_render_job`、`list_render_jobs` | 如果客户端需要一次拿到项目 metadata、当前画布文档、相关资产和实时 awareness，用 `export_project_snapshot`。如果媒体放置要跟随当前协作者的选区、视口、光标或正在编辑的文本节点，用 `get_live_canvas_context`。 ## 用量限制 Beta 阶段，MCP 用量使用较宽松的 rolling 7-day allowance： | Workspace | Beta MCP 工具调用额度 | | --------- | --------------------- | | Free | 1M/周 | | Creator | 1M/周 | | Pro | 1M/周 | | Team | 4M/周共享 | 这些 beta 额度在正式开放前可能调整。Beta 期间，Team workspace 每增加一个额外编辑席位，会增加每周 1M 次 MCP 工具调用。OAuth 握手、`initialize`、`tools/list` 和设置健康检查 `check_client_setup` 不计入额度；普通 `tools/call` 请求会计入。二进制上传字节、存储、AI 生成、云渲染和批量/API 工作仍由各自的限制和计费规则管理，不消耗 MCP call 额度。 通过 MCP 创建 AI 生成或云渲染任务时，仍然走正常的 Flares 报价和预留流程。MCP 额度只覆盖工具调用控制层。 ## 媒体放置 如果 agent 或 MCP 客户端生成的是本地图片文件，不要把 base64 或 data URL 塞进 MCP JSON。走二进制上传流程： 1. 调用 `create_image_upload_session`，传入 `fileName`、`fileSize`、`mimeType` 和来源信息。用 `sourceClient` 记录 agent/客户端（如 `codex`、`claude`、`chatgpt`），用 `generationModel` 记录真实生图模型，知道的话同时传 `generationPrompt`/`generationTool`。 2. 把本地文件字节 `POST` 到返回的 `uploadUrl`，请求头带上 `Authorization: Bearer `、`Content-Type` 和 `x-flare-file-size`。 3. 用上传返回的 `assetId` 和目标 `projectId` 调用 `insert_asset_image`。 这条路径创建的素材会记录为生成媒体，并标记 `ingestMethod: mcp-binary-upload`，不是普通用户上传。这样 Codex/Claude 生成的图可以按来源和 prompt 搜索，也不会伪造一个 Flare 内部生成任务。 如果客户端工具列表较旧，还没有 `create_image_upload_session`，可以调用 `get_image_upload_endpoint` 获取通用的短时 `uploadToken`，再用同样方式上传本地文件字节。 如果 agent 手里只有 data URL 或 base64 payload，应先把它保存成本地图片文件，再走二进制上传流程。不要在 shell 命令里搜索、暴露或复用 MCP OAuth access token。 如果图片已经是公开 HTTPS URL，可以用 `insert_agent_generated_image` 一步保存到 Assets 并放到画布上。`insert_generated_image` 和 `insert_codex_generated_image` 是兼容别名。这些工具用于 agent 已经生成或拿到的图片，不会启动 Flare/canvas 的生成任务。 已有账号媒体可以用 `insert_asset_image` 或 `insert_asset_video` 放入画布。视频放置支持 `autoplay`、`loop`、`muted` 和 `mediaFit`。 `insert_agent_generated_image`、`insert_generated_image`、`insert_codex_generated_image`、`insert_asset_image` 和 `insert_asset_video` 支持智能放置参数： - `anchorNodeId` 指定围绕哪个节点放置。 - `clientId` 指定读取哪个协作者的实时选区。 - `placement` 可选 `left`、`right`、`above`、`below`、`center`、`fill`。 - `fitSelection` 会让图片适配当前选区。 - `replaceNodeId` 会替换已有图片或视频节点的媒体来源。 - `x` 和 `y` 是以图层中心为准的 canvas scene 坐标。`width` 和 `height` 是未缩放尺寸。 - `parentId` 只改变层级或裁剪关系，坐标依然使用 canvas scene 坐标。 如果没有传入坐标，MCP server 会优先读取 `get_live_canvas_context` 的实时 presence：包括当前选区、视口、光标和正在编辑的文本节点。presence 只用于实时上下文，不会写进项目文档。 对生成图片来说，默认不要传 `parentId`。只有当用户明确要求把生成图片放进某个 frame 或 group 时，再传 `parentId`。 图片上传和远程图片导入上限都是 20 MB。二进制上传会话 10 分钟后过期。远程图片必须使用 HTTPS。 ## 批注改图 当用户在 Flare 里给图片图层加箭头、框选、圈选或文字批注，并让 Codex、Claude 等外部 agent 按批注改图时，先调用 `get_image_annotation_context`。这个工具会返回准确的目标图片节点、匹配到的素材和 provenance、带 0..1 归一化目标点的结构化箭头、区域和文字批注、可选的“目标图 + 批注”合成预览，以及建议把新版图片放在原图旁边的位置。 这条流程属于 agent 侧生图。Agent 应该用自己的图像生成或编辑能力生成新版图片，把结果保留为本地图片文件，通过 `create_image_upload_session` 二进制上传，再用 `insert_asset_image` 按建议位置放回画布。除非用户明确要求使用 Flare 后端生成，否则不要调用 `create_generation_job`。 ## HTML 导入 当 agent 手里有一段 HTML snippet 或完整 HTML document，并且用户希望放到画布上时，使用 `insert_html`。MCP server 会把一份 HTML 输入转换成一个根 Flare frame；支持的文字、简单盒子和公开 HTTPS 图片会变成这个 frame 里的可编辑子图层。 `insert_html` 是结构化、可编辑导入，不是高保真的浏览器截图。它不会运行 Playwright，也不会执行脚本。如果需要像素级浏览器渲染，应先在外部渲染成图片，把结果保存成本地图片文件，再用 `create_image_upload_session` 二进制上传，并通过 `insert_asset_image` 放到画布。 图片处理规则和生成图片一致。不要把 data URL、base64 字符串或本地图片路径放进 MCP JSON；先保存成本地文件，再按二进制资产上传。 ## 画布、媒体和时间线 直接编辑画布时，尽量优先使用更具体的工具： - 用 `insert_text`、`insert_rect`、`create_frame` 创建简单图层。 - 用 `update_text`、`set_layer_style`、`reorder_nodes`、`group_nodes`、`delete_nodes` 做聚焦编辑。 - 用 `apply_canvas_patch` 执行批量或混合编辑。单次 patch 最多 50 个 operation。 时间线相关能力： - `add_audio_track` 可以把账号音频资产加入项目时间线，并设置 trim、volume、fade、ducking。 - `add_caption_track` 可以添加手动字幕或 transcript 字幕 cue。 生成和渲染任务： - `create_generation_job`、`get_generation_job`、`list_generation_jobs` 使用和 app 一样的 Flare AI 后端队列。 - `create_render_job`、`get_render_job`、`list_render_jobs` 可以基于项目或显式 render snapshot 创建和查询云端渲染任务。 ## AI 设计 Motion 客户端可以先用 `get_live_canvas_context` 读取当前选中的画板，再用 `get_canvas_snapshot` 分析画板里的标题、图片、CTA 和层级关系。生成 motion plan 后调用 `apply_motion_design`： - 不传 `frameId` 时，server 会优先使用当前选中的 frame；如果选中的是 frame 内子图层，会自动找到所属 frame。 - `composition`、`durationMs`、`fps`、`posterTimeMs` 用于设置画板时长和播放参数。 - `layers` 里每一项用 `nodeId` 指向子图层，并可写入 `timeline`、`motionClips`、`animation` 或 `textAnimation`。 - `replaceExisting` 控制是否替换已有 motion clips；默认替换，适合 AI 重新设计整套动效。 ## 连通性测试 连接后，先让客户端列出项目，再对某个项目调用 `export_project_snapshot`。如果读取正常，可以在临时画布里插入一段小文字来验证写入能力。 如果客户端提示授权错误，重新连接并确认 resource URL 是 `https://mcp.flare.design/mcp`。