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 | 查詢上傳連結的狀態:等待中、上傳中、建置中、完成(場景和連結)、失敗或已過期。 |
每個工具都是透過 @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。