Verse
官方发布 3D 场景、漫游和世界,从单个产品到整座城市,都可以生成可在任何浏览器中打开的链接。你的助手会收到链接、嵌入代码、私密分享链接和导览。使用 Verse 登录,无需 API 密钥。
你可以用 Verse MCP 做什么?
- 发布场景 — 请助手上传本地文件或公开 URL,并返回 Verse 链接、嵌入代码或分享链接。
- 管理可见性 — 将场景设为公开、不公开列出或私密,并为私密场景获取可撤销的分享令牌链接。
- 查看构建状态 — 查询场景的构建状态、进度和预计完成时间,并在完成后获取链接。
- 获取嵌入代码 — 为已发布的场景请求 iframe、
<verse-viewer>元素或纯 URL 嵌入选项。 - 创作镜头导览 — 读取、设置、重新规划或删除场景飞行浏览的引导式镜头路径。
- 创建上传链接 — 为无法直接交付的文件生成一个 30 分钟内有效且仅可使用一次的链接,然后查询其状态。
托管 MCP 服务器
npx add-mcp 'https://verse.ctruh.com/mcp'可安装到 Claude Code、Codex、Cursor 等客户端
文档
@ctruhtech/verse-mcp
一个用于 Verse Engine 的 MCP 服务器,可将 3D 场景、漫游和世界(从单个产品到整座城市)发布为链接,在日常设备上的任何浏览器中打开。将它连接到 Claude、ChatGPT、Cursor、VS Code 或你自己的智能体后,助手便可发布文件或公开 URL,并返回 Verse 链接、嵌入代码、私密分享链接或引导式摄像机漫游。
"Put https://example.com/villa.glb on Verse and give me a link I can share."
"Make that scene private and give me a link I can send to the client."
"I have a big file on my phone. Give me a Verse upload link for it."
"Give me the embed code for it, 1:1."
采用 MIT 许可。文档:https://verse.ctruh.com/docs/#/mcp。提供一键按钮的安装页面:https://verse.ctruh.com/mcp。
一步连接:使用 Verse 登录
将 https://verse.ctruh.com/mcp 添加到你的助手,然后在浏览器中使用 Verse 账户登录。无需复制 API 密钥,也无需安装任何内容。
- Claude(网页端和桌面端):Settings → Connectors → Add custom connector → URL
https://verse.ctruh.com/mcp→ Add,然后点击 Connect。 - Claude Code:
claude mcp add --transport http --scope user verse https://verse.ctruh.com/mcp,然后运行/mcp并选择 Authenticate。 - ChatGPT: Settings → Connectors → Create (developer mode) → URL
https://verse.ctruh.com/mcp,将 authentication 设为 OAuth → Create,然后登录。 - Cursor:添加到 Cursor,或在
~/.cursor/mcp.json中使用{ "mcpServers": { "verse": { "url": "https://verse.ctruh.com/mcp" } } },然后在 Settings → MCP 中点击 Connect。 - VS Code:安装到 VS Code,或在
.vscode/mcp.json中使用{ "servers": { "verse": { "type": "http", "url": "https://verse.ctruh.com/mcp" } } },然后点击 Start。
首次使用时,Verse 页面会提示你登录(通过电子邮件或 WhatsApp 验证码),然后点击 Allow。应用会在你的账户页面创建一个名为“MCP · ”的密钥;密钥有效期为 30 天,在使用期间会自动续期,你也可以在该页面撤销密钥。
如果你更愿意使用 API 密钥在本地运行,请参阅下方的设置(stdio):npx -y @ctruhtech/verse-mcp,需要 Node 20 或更高版本。
工具
| 工具 | 功能 |
|---|---|
upload_scene | 将本地路径或公开 URL 转换为 Verse 链接。支持大文件断点续传、进度通知,并等待构建完成。 |
get_scene_status | 查看构建状态、进度和预计剩余时间;完成后提供链接。 |
list_scenes | 查看账户拥有的场景。 |
create_share_link | 设置可见性(公开 / 不公开 / 私密);私密场景会生成可撤销的分享令牌链接。可选自动播放摄像机路径。 |
revoke_share_link | 撤销私密分享令牌(或列出当前有效的令牌)。 |
get_embed_code | iframe、<verse-viewer> 元素和纯 URL。 |
list_camera_paths、set_camera_path、reset_auto_camera_path、delete_camera_path | 引导式漫游:读取、编写、重新规划自动飞行路线,或删除漫游。 |
create_upload_link | 适用于用户有文件但无法直接交给你的情况(例如聊天附件或手机上的文件):生成一个有效期 30 分钟、仅可使用一次的链接,用户可通过该链接上传文件;文件会保存到其账户中。 |
get_upload_link_status | 查看上传链接的状态:等待中、上传中、构建中、已完成(场景和链接)、失败或已过期。 |
每个工具都是对公开 REST API(API 参考)的轻量封装,通过 @ctruhtech/verse-sdk 调用。由于 API 没有相应端点,因此没有生成世界的工具。分享链接不会自动过期;API 不支持设置过期时间,因此要结束访问,请撤销私密链接。错误会以一条纯文本句子的形式返回。
凭据
将 VERSE_API_KEY 设置为以下其中一项:
- 账户页面(API keys 卡片)中的工作区 API 密钥
vk_...。该密钥以工作区成员身份运行,可用于上传、管理场景、设置可见性、管理私密链接和摄像机路径; - 你的账户令牌(64 位十六进制字符串,来自 Studio)。权限相同,但与个人账户绑定。
两者都会作为 Authorization: Bearer 发送。上传需要免费的 Verse 账户;打开已发布的链接则不需要。VERSE_BASE_URL 指向另一个源站(默认为 https://verse.ctruh.com)。密钥只会作为请求头发送到该源站,不会被记录日志,也不会在工具输出中返回。VERSE_UPLOAD_KEY(可选)是以密钥模式运行的自托管服务器的 X-API-Key。
设置(stdio)
Claude Desktop:~/Library/Application Support/Claude/claude_desktop_config.json(macOS)或 %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"verse": {
"command": "npx",
"args": ["-y", "@ctruhtech/verse-mcp"],
"env": { "VERSE_API_KEY": "paste-your-key" }
}
}
}
Claude Code:
claude mcp add verse --env VERSE_API_KEY=paste-your-key -- npx -y @ctruhtech/verse-mcp
Cursor:~/.cursor/mcp.json(或在项目中使用 .cursor/mcp.json),JSON 与 Claude Desktop 相同。
VS Code:.vscode/mcp.json:
{
"inputs": [{ "type": "promptString", "id": "verse-key", "description": "Verse API key", "password": true }],
"servers": {
"verse": {
"command": "npx",
"args": ["-y", "@ctruhtech/verse-mcp"],
"env": { "VERSE_API_KEY": "${input:verse-key}" }
}
}
}
远程(Streamable HTTP)
登录设置见本页顶部。API 密钥仍可使用:发送 Authorization: Bearer <key>(账户页面中的密钥或你的账户令牌),无需登录。
对于只接受固定请求头的客户端(托管式智能体、脚本):
{
"mcpServers": {
"verse": {
"url": "https://verse.ctruh.com/mcp",
"headers": { "Authorization": "Bearer paste-your-key" }
}
}
}
使用密钥而非登录的 Claude Code:claude mcp add --transport http verse https://verse.ctruh.com/mcp --header "Authorization: Bearer $VERSE_API_KEY"。请求之间不会保存任何内容,远程服务器也禁用了本地文件路径(请传入公开 URL)。如果请求未提供密钥或登录信息,服务器会返回 401,其中包含 WWW-Authenticate: Bearer realm="verse-mcp", resource_metadata="…" 和一条说明应发送何种内容的 JSON-RPC 错误。
自行托管:
VERSE_BASE_URL=https://verse.ctruh.com npx @ctruhtech/verse-mcp --http --port 8787 # http://127.0.0.1:8787/mcp
请在前面配置 TLS。若要将其挂载到现有的 Node 服务器中:
import { createHttpHandler } from "@ctruhtech/verse-mcp";
const mcp = createHttpHandler({ baseUrl: "https://verse.ctruh.com" });
// in your request listener: if (url.pathname === "/mcp") return mcp(req, res);
命令行
verse-mcp stdio server
verse-mcp --http [--port 8787] [--host 127.0.0.1] [--allow-anonymous]
verse-mcp --version
开发
npm install
npm run typecheck
npm test # scripted Verse origin, both transports, driven by the official MCP client
问题反馈和源代码:https://github.com/dev-vinayagastya/verse-mcp。许可:MIT,详见 LICENSE。