Scribis AI Agent Skills & MCP 整合指南
把 Claude Code、Claude Desktop、Cursor、OpenAI Codex、Google Antigravity、Windsurf 等 MCP Host 連上 Scribis Desktop,讓 AI 助手直接在執行中的 App 裡本機轉錄、修字幕、粗剪、加動態圖卡、音樂與配音。
download下載 scribis.install-skill.zipZIP 解壓後只有一個 mcp_client/ 資料夾,內含 11 個 Agent Skills、bridge.js、scribis CLI 與示範用 client。請把它移到固定位置,以下範例以 /path/to/mcp_client 代稱。macOS 若解壓出 __MACOSX/ 資料夾,可直接忽略。
checklist開始之前
- 已安裝並開啟 Scribis Desktop。
- 在「設定 → MCP協定」啟用 MCP。該頁會顯示目前的 Port(預設 8890),並提供各 Host 可直接複製的設定。
- Node.js 18 以上,只有 bridge.js、scribis CLI 與示範 client 需要。bridge 與 CLI 沒有相依套件,不需要 npm install。
1. 安裝 Agent Skills
Skills 會教 AI 助手如何使用 Scribis。請把每個 skills/scribis-* 資料夾複製到 AI 助手的 skills 目錄。
scribis-transcribe核心 Skill:轉錄、字幕/SRT、即時語音轉文字、粗剪、放大、馬賽克、場景、TTS、畫面預覽與 scribis CLI。
scribis-edit從 Scribis 複製的指令(/scribis-edit cuts <id>、/scribis-edit scene <id>):開啟對應的編輯器並分派需求。
scribis-motion動態標題、數字圖表、標註、下方字卡等 HTML 動態圖卡,以及單一細節的修改。
scribis-audio背景音樂與音效:素材庫搜尋、匯入、產生音效、淡入淡出、說話時壓低音樂與音量檢查。
scribis-voice旁白配音(TTS)、用講者本人或複製的聲音重念一句,以及讓動畫對齊說話的字詞。
scribis-explainer從報告、數據或 YouTube 影片製作短版說明動畫與數據故事,以可個別編輯的段落組成場景。
scribis-earshot聽覺驗證:判斷音效是否符合描述、標註聲音類別、在錄音中找片段,並量測響度與峰值,模型在本機執行。
scribis-writing依簡報、文章或 Scribis 逐字稿做研究、撰寫旁白與腳本、修稿、摘要與翻譯;純寫作不需連線 App。
scribis-color場景自動調色:依量測結果校正曝光與白平衡、讓鏡頭比對參考片段,並套用風格。
scribis-storyboard依腳本與素材資料夾做分鏡,為每組段落產生符合風格的動態圖像,經審稿後在場景編輯器確認。
scribis-2d-video把腳本做成故事影片:可編輯的 HTML 鏡頭搭配旁白、字幕、配樂與音效,提供火柴人、水彩繪本與任一動態風格。
| AI 助手 | 專案(僅此 repository) | 個人(所有專案) |
|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| OpenAI Codex | .agents/skills/ | ~/.agents/skills/ |
| Google Antigravity | .agents/skills/ | ~/.gemini/config/skills/舊版: ~/.gemini/antigravity/skills/ |
| Cursor | .cursor/skills/ · .agents/skills/ | ~/.cursor/skills/ · ~/.agents/skills/ |
| Windsurf | .windsurf/skills/ · .agents/skills/ | ~/.codeium/windsurf/skills/ · ~/.agents/skills/ |
| 其他支援 Agent Skills 的 Host | .agents/skills/ | ~/.agents/skills/ |
mkdir -p ~/.claude/skills cp -R /path/to/mcp_client/skills/scribis-* ~/.claude/skills/
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null Copy-Item -Recurse -Force C:\path\to\mcp_client\skills\scribis-* "$env:USERPROFILE\.claude\skills"
Cursor 也會讀取 .claude/skills/,所以裝一次 Claude Code 即可兩者共用。Skills 目錄可能隨 Host 版本變動;若沒有被讀到,請查閱該 Host 的文件。安裝後請重新啟動 AI 助手(或開新的 session)。
2. 將 Scribis 連到 MCP Host
大多數 Host 直接透過 localhost HTTP 連到 Scribis 的 MCP 端點。請把 <port> 換成「設定 → MCP協定」顯示的 Port(預設 8890)。
| Host | 設定檔 | 設定內容 |
|---|---|---|
| Claude Code | .mcp.json | {"mcpServers": {"scribis": {"type": "http", "url": "http://127.0.0.1:<port>/mcp"}}}請保留 "type": "http",少了它會被當成 stdio server。 |
| Claude Desktop | claude_desktop_config.json | 僅支援 stdio:請使用下方的 bridge.js。 |
| Cursor | .cursor/mcp.json · ~/.cursor/mcp.json | {"mcpServers": {"scribis": {"url": "http://127.0.0.1:<port>/mcp"}}} |
| OpenAI Codex | ~/.codex/config.toml | [mcp_servers.scribis]
url = "http://127.0.0.1:<port>/mcp" |
| Google Antigravity | mcp_config.json | {"mcpServers": {"scribis": {"serverUrl": "http://127.0.0.1:<port>/mcp"}}}Antigravity 必須使用 serverUrl。 |
| Windsurf | mcp_config.json | {"mcpServers": {"scribis": {"serverUrl": "http://127.0.0.1:<port>/mcp"}}}也接受 url。 |
| 其他支援 Agent Skills 的 Host | mcp.json | {"mcpServers": {"scribis": {"url": "http://127.0.0.1:<port>/mcp"}}}或使用下方的 stdio bridge。 |
claude mcp add --transport http scribis http://127.0.0.1:8890/mcp
stdio Host:bridge.js
只能啟動本機程序的 Host(例如 Claude Desktop)請使用 bridge.js。它會自動找到執行中的 Scribis,不需要 Port。
{
"mcpServers": {
"scribis": {
"command": "node",
"args": ["/path/to/mcp_client/bridge.js"]
}
}
}{
"mcpServers": {
"scribis": {
"command": "node",
"args": ["/path/to/mcp_client/bridge.js"],
"env": {
"SCRIBIS_USER_DATA_PATH": "/path/to/scribis-data"
}
}
}
}{
"mcpServers": {
"scribis": {
"command": "scribis",
"args": ["mcp-bridge"]
}
}
}3. 安裝 scribis CLI(選用)
CLI 適合在終端機操作,也適合有 shell 權限但沒有原生 MCP 工具的 AI 助手。
cd /path/to/mcp_client/cli node bin/scribis.js install-cli
scribis status # Check the connection to Scribis scribis models # List ASR models and whether each is installed scribis transcribe meeting.mp4 --output srt -o meeting.srt scribis transcribe meeting.mp4 --model large-v3 --lang en --output srt ffmpeg -re -i talk.wav -ar 16000 -ac 1 -f s16le - | scribis stream --vad --lang auto scribis open youtube https://youtu.be/<video_id> scribis open cuts <project_id> scribis open scene <scene_id> scribis youtube captions https://youtu.be/<video_id> --lang en --output srt -o talk.srt scribis youtube quota scribis youtube history
CLI 不會下載模型:請先執行 scribis models,缺少的模型到「設定 → 模型」下載。指令失敗時結束碼為 1。
4. 各平台的連線方式
bridge 與 CLI 預設透過本機 Socket 連線,並會自動找到 Scribis。localhost HTTP 端點在所有版本都能使用,所以用 HTTP URL 設定的 MCP Host 不需其他設定。
| 版本 | 預設(bridge.js、scribis …) | 備援(localhost HTTP) |
|---|---|---|
| Windows | Named pipe,不需 Port | http://127.0.0.1:<port>/mcp scribis … --mcp |
| macOS(官網下載版) | Unix domain socket,不需 Port | http://127.0.0.1:<port>/mcp scribis … --mcp |
| macOS(Mac App Store) | 位於 Scribis App Group 容器的 Unix domain socket,自動尋找 | http://127.0.0.1:<port>/mcp scribis … --mcp |
CLI 使用 --mcp(HTTP)
在任何 CLI 指令加上 --mcp 即改用 localhost HTTP。CLI 會讀取執行中 App 公布的 Port;只有要強制指定 Port 時才需設定 SCRIBIS_MCP_PORT。
scribis status --mcp
SCRIBIS_MCP_PORT=8890 scribis status --mcpWindows (PowerShell):$env:SCRIBIS_MCP_PORT="8890"; scribis status --mcp🍎 Mac App Store 版
- 終端機或 MCP Host 第一次讀取 Scribis 的 App Group 容器時,macOS 可能會詢問是否允許存取其他 App 的資料。請允許,bridge 與 CLI 才能找到 Scribis。
- 若 scribis status 回報「stdio socket is unavailable」,請改用 HTTP:scribis … --mcp,或 http://127.0.0.1:<port>/mcp。錯誤訊息會列出要用的 Port。
- Scribis 只能讀取您已授權的檔案。若工具讀不到檔案,請先在 Scribis 中開啟或匯入該檔案(或將其資料夾加入同步資料夾)。
5. 測試與疑難排解
Scribis 開啟且已啟用 MCP 時,執行 scribis status,正常會顯示 Connected。接著可以對 AI 助手說:「用 Scribis 轉錄 ~/Movies/meeting.mp4 並存成 SRT」或「剪掉這段影片的口頭禪和停頓」。
| 訊息或狀況 | 處理方式 |
|---|---|
| Unable to reach / 連線錯誤 | 開啟 Scribis Desktop,並確認「設定 → MCP協定」已啟用 MCP 伺服器。 |
| Stale MCP discovery | Scribis 未正常關閉。請重新啟動 Scribis,或在設定中關閉再開啟 MCP 伺服器。 |
| stdio socket is unavailable | 改用 HTTP:scribis … --mcp,或在 MCP Host 使用 http://127.0.0.1:<port>/mcp。 |
| --mcp 找不到 Port | 將 SCRIBIS_MCP_PORT 設為「設定 → MCP協定」顯示的 Port。 |
| Skills 沒有被讀到 | 確認該 Host 與版本的 skills 目錄、所有 scribis-* 資料夾放在同一層,並開新的 session。 |
| 模型未安裝 | 執行 scribis models,再到「設定 → 模型」下載。 |
| Scribis 使用自訂資料夾 | 為 bridge 與 CLI 設定 SCRIBIS_USER_DATA_PATH(或 SCRIBIS_DISCOVERY_PATH / SCRIBIS_SOCKET_PATH)。 |
shield安全性
- MCP 端點只接受來自您本機的連線(127.0.0.1、localhost、[::1]),網站與其他主機的請求都會被拒絕,因此不需要 token。
- Scribis 在同一個 Port 也提供 OpenAI 相容的 REST API(/v1),以您在「設定 → MCP協定」建立的 API Key 保護。對外開放前,請先閱讀套件中的 README.md。