进阶 docs.spline.design 2026-11-22 06:55:33 · 1 阅读

第5章 Spline MCP Server:连接 AI 工具与 3D 设计场景

第5章 Spline MCP Server

Spline MCP Server 让 ChatGPT、Claude、Cursor、Codex、Antigravity 等 AI 工具直接连接 Spline。借助 Model Context Protocol(MCP),任何兼容 MCP 的客户端都能为你搭建和编辑 Spline 3D 场景及 Hana 设计——创建文件、生成 3D 模型和图片、编写布局、执行修改——产出的结果是可编辑的 Spline 文件,而不是你需要维护的代码。

用 ChatGPT 或 Codex?添加 Spline 插件即可:Spline in ChatGPT and Codex 有你需要的一切。其他工具则有两种连接方式:

托管服务器:用 Spline 账号登录后,Agent 在 Spline 云端编辑器中工作。无需安装任何东西——是在 ChatGPT、Claude、Cursor 和 Codex 中上手的最快方式。

桌面应用:内置于 Spline 桌面应用中的服务器。Agent 在你本机上运行,直接编辑你打开的文件。

Agent 不支持 MCP?它仍可以阅读这些文档:llms.txt 索引了每个页面,llms-full.txt 将全部内容合并在一个文件中;在任何页面 URL 后加 .md 即可得到 Markdown 格式,比如本页对应 docs.spline.design/generate/spline-mcp-server.md。

托管服务器

托管服务器地址为 https://mcp.spline.design/mcp。你的 AI 工具通过互联网连接它,并用 Spline 账号登录;之后每次调用都在云端的一个 Spline 编辑器中执行(每个会话一个编辑器)。你本机不需要打开任何东西——即使没有任何 Spline 标签页,Agent 也会持续工作。

``` 你 ──► AI 工具 ──► mcp.spline.design ──► 云端 Spline 编辑器 提示词 (ChatGPT, Claude, (登录一次) (Spline 3D 或 Hana) Cursor, Codex, …) ```

连接你的 AI 工具

所有客户端的地址都一样:https://mcp.spline.design/mcp。选择你的工具:

ChatGPT:从 ChatGPT 的插件目录添加 Spline 插件。Spline 编辑器会在聊天旁边的面板中打开。设置、面板和示例提示见 Spline in ChatGPT and Codex。

Codex:添加同一个 Spline 插件,或仅添加服务器(codex mcp add spline --url https://mcp.spline.design/mcp),再用 codex mcp login spline 登录。详见 Spline in ChatGPT and Codex。

Claude Code: ``` claude mcp add --transport http --scope user spline https://mcp.spline.design/mcp ``` --scope user 让 Spline 在所有项目中可用;省略该参数则只在当前项目中添加。然后在 Claude Code 中运行 /mcp,选择 spline 并选择 Authenticate 登录。

Cursor:将服务器添加到 ~/.cursor/mcp.json(所有项目)或 .cursor/mcp.json(单个项目): ```json { "mcpServers": { "spline": { "url": "https://mcp.spline.design/mcp" } } } ``` 然后打开 Cursor Settings → MCP,找到 spline 并从那里登录。

Claude(桌面版或网页版):打开 Settings → Connectors,选择 Add custom connector,命名为 Spline 并填入 https://mcp.spline.design/mcp,然后选择 Connect 登录。

VS Code:将服务器添加到项目中的 .vscode/mcp.json: ```json { "servers": { "spline": { "type": "http", "url": "https://mcp.spline.design/mcp" } } } ``` 服务器首次启动时 VS Code 会要求你登录。

其他 MCP 客户端:任何支持远程(streamable HTTP)服务器并带 OAuth 登录的 MCP 客户端都可以使用托管服务器。添加远程服务器,URL 填 https://mcp.spline.design/mcp;如果客户端要求选择 transport,选 streamable HTTP。

希望 Agent 自己主动使用 Spline 并一次写对?在服务器旁边再添加 Spline Agent Skill。这是可选的:没有它工具照常工作。

登录

登录时,你的 AI 工具会打开一个浏览器窗口,你在其中登录 Spline 并授权访问。有些工具只在 Agent 第一次调用 Spline 工具时才会这样做。之后 Agent 就在你的 Spline 账号中工作:它创建的文件像其他文件一样保存在那里,也能打开你已有的文件。

要断开连接,从 AI 工具中移除该服务器即可。

使用方法

直接说出你想要的东西——不需要先打开文件。

"创建一个 3D 场景:底座上有一个旋转的玻璃球,配上柔和的摄影棚灯光。" "设计一个简洁的定价页,包含三个档位和一个行动号召按钮。"

Agent 创建或打开文件后,会给你一个指向 Spline 网页编辑器的链接(在 ChatGPT 中,文件则直接在 Spline 面板中打开)。在浏览器中打开它,可以实时观看设计逐步成形,也可以自己继续编辑——在画布上操作,或者让 Agent 改。同一会话中的后续请求会继续处理同一个文件。

想把成果引入你的代码库?Agent 可以将 Hana 画框当前的 HTML + CSS(包括你手动做的修改)导出,并适配到你的项目中。对于 3D 场景,让 Agent 发布它:它会更新场景的公开 URL、Viewer 嵌入或代码导出,并把可嵌入的线上链接交给你。详见 Working with your codebase。

Agent 能做什么

托管服务器提供与桌面应用相同的工具,但不包括读取你本机文件的那部分:

Spline 3D 方面

- 创建和打开 3D 文件,搭建或编辑场景。 - 用 Spline AI 生成 3D 模型和图片。 - 检查场景和对象、设置相机视角、截图来检查自己的工作。 - 在画布之上编写代码层——HUD、界面和游戏逻辑。 - 将场景发布到其公开 URL、Spline Viewer 嵌入或代码导出,并把链接交给你。只有在你要求时才会发布。

Hana 方面

- 创建和打开 Hana 文件,设计或重建画框(网页、应用界面、UI)。 - 添加、移动、复制、调整大小、改色和更新对象。 - 生成和编辑图片、审查画框,并导出为 HTML + CSS。

要在 Hana 中使用你自己的图片,可以在编辑器中把它们添加到文件里,或者使用桌面应用——它的 Agent 可以上传你本机的文件。每个工具都在工具参考中按名称列出。

用量限制

Agent 的每次工具调用都会计入你的 Spline 套餐设定的每日额度,所有套餐还有每分钟短时限额,以防止失控循环。阅读指南和查看个人资料不计入;Spline 侧失败的调用会返还。可以问 Agent 今天还剩多少次调用:它能查询你的套餐和今日用量。达到限制时,Agent 会被告知是哪个限制以及何时重置——每日额度在 UTC 午夜重置,每分钟限额一分钟内重置——以及在哪里升级。升级从下一次调用起生效。

隐私与安全

- 登录使用 OAuth:你的 AI 工具永远看不到你的 Spline 密码,只拿到一个代表你调用 Spline 工具的令牌。从工具中移除服务器即可停止其调用。 - Agent 的调用和结果在你的 AI 工具与 Spline 服务器之间传输,并在云端的一个 Spline 编辑器中执行。它处理的文件像其他文件一样存储在你的 Spline 账号中。

故障排查

桌面应用

桌面服务器把你的 AI 编程工具连接到 Spline 桌面应用中打开的编辑器标签页,完全在你本机上运行。

下载 Spline 桌面应用:使用桌面服务器的必要条件。支持 macOS 和 Windows。

桌面服务器内置于 Spline 桌面应用,无法在浏览器中使用。没有需要单独安装的包:下载并打开桌面应用即完成全部设置。不想用应用就用托管服务器。

工作原理

桌面服务器在你的 AI 编程工具和 Spline 桌面应用中打开的编辑器标签页之间搭桥:

``` 你 ──► AI 编程工具 ──► Spline MCP Server ──► 你打开的编辑器标签页 提示词 (Claude, Cursor, (随应用附带) (Spline 3D 或 Hana) Codex, …) ```

1. 你向 AI 工具描述需求(例如"加一个浮岛场景")。 2. AI 工具判断需要调用哪些 Spline 工具,以结构化请求的形式发出——工具名加参数,而不是你的提示词原文。 3. Spline 应用把每次调用路由到正确的编辑器标签页;如果没有打开相应类型的文件,会为你新建一个。 4. 标签页对你当前的文档执行调用并返回结果,AI 工具继续调用直到任务完成。

由于调用在编辑器标签页内执行,AI 工具可以访问场景、对象、材质、相机,以及 Spline 的 AI 生成功能。

一个服务器,两个入口。同一条连接同时驱动两个产品。请求会按类型自动路由:

- 3D 请求(场景、网格、相机、灯光)路由到你的 Spline 3D 标签页。 - 2D / Hana 请求(网站、应用界面、UI、布局)路由到你的 Hana 标签页。

所有通信都通过 127.0.0.1 在你本机上进行。桌面服务器不会把你的工作暴露到互联网——请求和结果只在 Spline 应用与你连接的 AI 客户端之间传输。

系统要求

- Spline 桌面应用(macOS 或 Windows)——必需,因为桌面服务器内置于其中,无法在浏览器中运行。 - 一个兼容 MCP 的 AI 编程工具: - Claude Code、Claude Desktop、Cursor、VS Code、Antigravity 和 ChatGPT——自动配置。 - Windsurf 及其他兼容 MCP 的客户端——简单的首次设置,见连接其他客户端。

设置

自动设置

安装并打开 Spline 桌面应用时,它会自动为检测到的每个受支持客户端注册 MCP 服务器,无需手动改配置。

| 客户端 | Spline 写入配置的位置 | |---|---| | Claude Code | ~/.claude.json | | Claude Desktop | claude_desktop_config.json(含 Windows MSIX 安装) | | Cursor | Cursor 的 MCP 配置 | | VS Code | VS Code 和 VS Code Insiders | | Antigravity | Antigravity 的 MCP 配置(新旧路径均支持) | | ChatGPT | ChatGPT 桌面应用内置的 codex CLI(TOML 配置) |

1. 下载 Spline 桌面应用(macOS 或 Windows)并至少打开一次。这一步必需——桌面服务器在应用内。 2. 重启你的 AI 客户端以加载新服务器。大多数客户端只在启动时加载 MCP 服务器。 3. 完成——Spline 的工具现在对 Agent 可用了。

你可以在 Spline 的 MCP 设置中按客户端管理:其中列出每个受支持的客户端(各有独立开关)外加一个全局开关,展开某个客户端还能看到它的具体设置步骤。

要确认连接,工具会以 Spline 命名空间出现在你的客户端中(例如 mcp__Spline__3d_run_code 或 mcp__Spline__2d_write_html)。

连接其他客户端

对于 Spline 不自动配置的兼容 MCP 的工具(例如 Windsurf),把生成的服务器条目复制到该工具的 MCP 配置里。Spline 的 MCP 设置中有一个 Other agents 面板,直接给出可粘贴的条目,路径已根据你的安装自动解析。

应用生成的条目位于以下位置 Spline 键的下面:

- Claude Code — ~/.claude.json - Claude Desktop — - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

条目大致如下(具体路径因机器和安装方式而异): ```json { "mcpServers": { "Spline": { "type": "stdio", "command": "/path/to/Spline.app/.../MacOS/Spline", "args": ["/path/to/spline-mcp.cjs"], "env": { "ELECTRON_RUN_AS_NODE": "1" } } } } ``` 把 Spline 条目复制到你想用的工具的 MCP 配置中,然后重启它。大多数工具接受同样的 command/args/env 结构;如果配置格式不同,请查阅该工具的 MCP 文档。

由于应用会在更新和移动后自动维护自己的条目,保持最新的最简单方式是:让 Spline 管理它支持的客户端,路径变化时从其中一个客户端复制条目即可。

使用方法

1. 打开 Spline 桌面应用并保持运行。 2. 在 AI 客户端中直接说出你想要的东西。不必先打开文件——如果没有匹配的文件打开着,Agent 会新建一个并在标签页中打开。

示例提示:

"创建一个 3D 场景:底座上有一个旋转的玻璃球,配上柔和的摄影棚灯光。" "在 Hana 中设计一个简洁的定价页,包含三个档位和一个行动号召按钮。" "生成一个低多边形树的 3D 模型,加到我的场景里。" "把 src/app/dashboard/page.tsx 里的仪表盘页面在 Hana 中重建,方便我重新设计。" "我在 Hana 里调整好了布局——导出它并更新仓库里对应的组件。"

Agent 会自动选择正确的入口:设计请求走 Hana,3D 请求走 Spline 3D。如果两类都开着,调用会路由到对应类型中最近聚焦的标签页。

希望 Agent 自己选择 Spline 并一次写对创作规范?安装 Spline Agent Skill。它是可选的,没有它 MCP 服务器照常工作。

Agent 工作时,它正在编辑的画框或场景会高亮显示,你可以实时跟看。可以同时连接多个会话——它们都路由到同一个运行中的编辑器。

Agent 能做什么

连接后,Agent 可以(不限于此):

Spline 3D 方面

- 创建新的 3D 文件,搭建或编辑场景。 - 用 Spline AI 生成 3D 模型和图片。 - 检查场景和对象、执行场景修改、设置相机视角、截图。 - 在画布之上编写代码层——HUD、界面和游戏逻辑。见 Preview / Edit / Code 标签页和 AI Agent。 - 在你要求时把场景发布到公开 URL、Spline Viewer 嵌入或代码导出,并给你线上链接。

Hana 方面

- 创建新的 Hana 文件,设计或重建画框(网页、应用界面、UI)。 - 添加、移动、复制、调整大小、改色和更新对象。 - 生成和编辑图片、上传你本机的图片和其他素材、使用 3D 形状、应用效果并导出设计。

每个工具都在工具参考中按名称列出。

MCP 设置

在 Spline 应用中打开 Settings → MCP。每个受支持的客户端各占一行并带开关,你可以只连接 Claude Code 而不动 Cursor。展开某行可看到该客户端的具体设置步骤。

关闭某个客户端会从其配置中移除 Spline 条目并阻止重新添加;重新打开则会再次注册。Agent 只在启动时加载 MCP 服务器,所以 Spline 会提醒你重启刚开启的那个客户端。

如果你手动从配置中删除了 Spline 条目,Spline 会视为你有意退出,不会再加回来。

连接状态

每一行会显示该客户端当前是否在与 Spline 通信:

| 显示 | 含义 | |---|---| | Connected | 该客户端当前与 Spline 有活动会话 | | Starts on use | 已注册且正常,但该客户端只有在你实际使用时才建立连接——VS Code 和 ChatGPT 属于这种情况 | | 无标签 | 已注册且空闲 |

"Starts on use"不是问题。VS Code 和 ChatGPT 打开时不会启动连接,在客户端里发一条消息它就会连上。

应用侧边栏还有一个 MCP 状态指示器——点击它可以直接跳到这些设置。

隐私与安全

- 服务器只绑定 127.0.0.1——网络上无法访问。 - 连接受 origin 白名单限制,任意网页无法触达。没有需要管理的令牌。 - 你的场景和提示词只留在 Spline 应用与你连接的 AI 客户端之间。(Agent 使用的 Spline AI 生成功能在云端运行,与你在编辑器中使用时相同。)

故障排查

与你的代码库协作

你的 AI 编程工具已经在你的仓库里工作,Spline 可以直接嵌入你的设计到代码的流程中,而不是孤立的另一个工具。托管服务器和桌面应用都支持这些用法。

Spline 3D

把场景放进你的应用。让 Agent 发布场景,它会返回公开 URL、Spline Viewer 嵌入,或面向 React、Next.js、Vanilla JS、three.js 或 react-three-fiber 的代码导出,并接入你的项目。再次发布更新同一个链接,因此场景变化无需改代码就能在应用中生效。

把 UI 和逻辑带进场景。每个场景都有一个代码层:覆盖在画布之上的完整 HTML、CSS 和 JS 文档,用于 HUD、表单、界面和游戏逻辑。Agent 可以根据你仓库中的代码来编写它、就地编辑,再读回来保持源码同步。

基于项目内容搭建。让 Agent 看你仓库里已有的东西——品牌色、文案、产品列表——它会据此搭建或更新场景。

Hana

把页面带进 Hana。让 Agent 看你仓库中的某个页面或组件,它会把该界面重建为活的 Hana 画框——把标记语言转换为 Hana 支持的 HTML + CSS(flexbox)子集。之后你可以在画布上可视化地重新设计。

在 Hana 中用代码搭界面。也可以让 Agent 直接用 HTML + CSS 编写画框,你用代码描述的界面就会变成可编辑的 Hana 设计。

把画布上的修改推回代码。你在 Hana 中调整设计后,Agent 会把画框当前状态导出为 HTML + CSS,并把改动转换到你的框架——Next.js、Vue、纯 HTML 等。每个导出的元素都保留指向其 Hana 对象的稳定引用,Agent 因此能把视觉改动映射到源码中正确的位置。

Hana 的往返转换在 Hana 支持的 HTML + CSS 子集内进行。复杂或框架特定的标记可能需要 Agent 将导出的 HTML 与你现有组件做协调,而不是整体替换。

工具参考

Agent 可调用的每个工具,按名称列出,并标注提供它的服务器。你的 AI 客户端显示的名称与此一致,所以某个工具似乎缺失时对着这份清单核对即可。名称和工具会随 Spline 新功能而变化。

文件与账号

| 工具 | 功能 | 托管 | 桌面 | |---|---|---|---| | spline_canvas | 展示你的 Spline 文件(在 ChatGPT 中显示于 Spline 面板)。 | ✓ | | | spline_create_file | 在你的账号中创建 3D 或 Hana 文件并返回链接。 | ✓ | | | spline_open_file | 打开你的一个文件供 Agent 处理。 | ✓ | | | spline_profile | 你的账号、套餐,以及今日调用数与每日限额的对比。 | ✓ | |

Spline 3D

| 工具 | 功能 | 托管 | 桌面 | |---|---|---|---| | 3d_analyze_scene | 运行 Performance 面板背后的性能分析。 | ✓ | ✓ | | 3d_create_file | 在桌面应用中创建并打开 3D 文件。 | | ✓ | | 3d_edit_html_content | 对代码层进行定向修改。 | ✓ | ✓ | | 3d_generate_3d_model | 用 Spline AI 开始生成 3D 模型。 | ✓ | ✓ | | 3d_generate_image | 用 Spline AI 开始生成图片。 | ✓ | ✓ | | 3d_get_comments | 读取文件的评论串(钉在场景对象上)。 | ✓ | ✓ | | 3d_get_generation | 查询生成任务并获取图片或模型。 | ✓ | ✓ | | 3d_get_html_content | 读取代码层。 | ✓ | ✓ | | 3d_get_objects | 读取特定对象的完整细节。 | ✓ | ✓ | | 3d_get_scene | 读取场景中每个对象的简要摘要。 | ✓ | ✓ | | 3d_get_scene_mcp | 读取场景及一个可搭建的空位:通常的首次调用。 | ✓ | ✓ | | 3d_list_versions | 列出文件已保存的版本,以便回退。 | ✓ | ✓ | | 3d_load_skill | 加载 Spline 的 3D 创作指南。 | ✓ | ✓ | | 3d_publish_export | 将场景发布到公开 URL、Viewer 嵌入或代码导出。仅在你要求时。 | ✓ | ✓ | | 3d_reply_to_comment | 回复评论串,说明修改了什么。 | ✓ | ✓ | | 3d_resolve_comment | 将评论串标记为已解决。 | ✓ | ✓ | | 3d_restore_version | 将文件回滚到已保存版本,当前状态保留在历史中。付费套餐。 | ✓ | ✓ | | 3d_run_code | 搭建、编辑或给场景中的任何东西加动画:对象、材质、灯光、相机、交互。 | ✓ | ✓ | | 3d_set_html_content | 设置画布上的代码层:用于 HUD、界面和游戏逻辑的 HTML、CSS 和 JS。 | ✓ | ✓ | | 3d_set_view | 调整 Agent 自己的截图相机视角。 | ✓ | ✓ | | 3d_take_screenshot | 从 Agent 的相机截图,不影响你的视图。 | ✓ | ✓ |

Hana

| 工具 | 功能 | 托管 | 桌面 | |---|---|---|---| | 2d_add_objects | 在画框内添加对象。 | ✓ | ✓ | | 2d_create_file | 在桌面应用中创建并打开 Hana 文件。 | | ✓ | | 2d_delete_objects | 删除对象。 | ✓ | ✓ | | 2d_duplicate_objects | 复制对象,可带偏移。 | ✓ | ✓ | | 2d_edit_image | 用 AI 编辑图片:去背景或描述改动。 | ✓ | ✓ | | 2d_export_html | 将画框当前设计(含手动修改)导出为 HTML 和 CSS。 | ✓ | ✓ | | 2d_find_space | 在画布上为新画框找空位。 | ✓ | ✓ | | 2d_generate_images | 用 AI 开始生成图片,供使用它们的画框就绪。 | ✓ | ✓ | | 2d_get_canvas_state | 读取当前选区和画布上的空位。 | ✓ | ✓ | | 2d_get_object | 读取单个对象的完整属性。 | ✓ | ✓ | | 2d_get_scene | 读取场景树概览。 | ✓ | ✓ | | 2d_list_versions | 列出文件已保存的版本,以便回退。 | ✓ | ✓ | | 2d_load_skill | 加载 Spline 的 Hana 创作指南。 | ✓ | ✓ | | 2d_move_objects | 重新设置对象的父级或调整层级顺序。 | ✓ | ✓ | | 2d_recolor | 按颜色值在设计范围内批量换色,实现换肤。 | ✓ | ✓ | | 2d_reserve_frames | 为待设计的界面放置空画框。 | ✓ | ✓ | | 2d_resize_frame | 将画框调整为所设计页面的尺寸。 | ✓ | ✓ | | 2d_restore_version | 将文件回滚到已保存版本,当前状态保留在历史中。付费套餐。 | ✓ | ✓ | | 2d_review_frame | 截图画框并附带对象位置图,用于检查设计。 | ✓ | ✓ | | 2d_update_objects | 修改一个或多个对象的属性。 | ✓ | ✓ | | 2d_update_scene | 修改场景设置,如画布背景。 | ✓ | ✓ | | 2d_upload_assets | 向文件添加图片:桌面版来自你本机;托管服务器通过链接或 ChatGPT 附件。 | ✓ | ✓ | | 2d_write_html | 用 HTML 和 CSS 设计或重建画框。 | ✓ | ✓ |

AI 3D Generation 上一页

ChatGPT 和 Codex:在 ChatGPT 或 Codex 中添加 Spline 插件,在直接嵌入聊天的 Spline 编辑器里搭建 3D 场景和设计。

评论 (0)