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 MCP server

一個適用於 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_codeiframe、<verse-viewer> 元素和純文字 URL。
list_camera_paths、set_camera_path、reset_auto_camera_path、delete_camera_path導覽式旅程:讀取、編寫、重新規劃自動飛行導覽,或刪除旅程。
create_upload_link適用於使用者有檔案但無法直接交付的情況(例如聊天附件或手機上的檔案):建立一個 30 分鐘有效、僅能使用一次的連結,讓使用者上傳檔案;檔案會存入其帳戶。
get_upload_link_status查詢上傳連結的狀態:等待中、上傳中、建置中、完成(場景和連結)、失敗或已過期。

每個工具都是透過 @ctruhtech/verse-sdk 對公開 REST API(API 參考)的輕量封裝。由於 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。