Model Context Protocol & AI Agent Skills

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.zip

ZIP 解壓後只有一個 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。
psychology

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 鏡頭搭配旁白、字幕、配樂與音效,提供火柴人、水彩繪本與任一動態風格。

所有 Skills 請一起安裝、放在同一層。它們以相對路徑互相連結,只裝其中一個會有失效的連結。
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/
範例:macOS / Linux 的 Claude Code
mkdir -p ~/.claude/skills
cp -R /path/to/mcp_client/skills/scribis-* ~/.claude/skills/
範例:Windows(PowerShell)的 Claude Code
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)。

💡 在 Scribis 的「Cuts → 最近編輯」與「場景」中,「開啟」旁的複製按鈕會複製 /scribis-edit cuts <id> 或 /scribis-edit scene <id>。貼到 AI 助手後,scribis-edit Skill 會直接開啟該專案並開始處理。
settings_ethernet

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 Desktopclaude_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 Antigravitymcp_config.json{"mcpServers": {"scribis": {"serverUrl": "http://127.0.0.1:<port>/mcp"}}}Antigravity 必須使用 serverUrl。
Windsurfmcp_config.json{"mcpServers": {"scribis": {"serverUrl": "http://127.0.0.1:<port>/mcp"}}}也接受 url。
其他支援 Agent Skills 的 Hostmcp.json{"mcpServers": {"scribis": {"url": "http://127.0.0.1:<port>/mcp"}}}或使用下方的 stdio bridge。
Claude Code 也可以直接在終端機加入:
claude mcp add --transport http scribis http://127.0.0.1:8890/mcp

stdio Host:bridge.js

只能啟動本機程序的 Host(例如 Claude Desktop)請使用 bridge.js。它會自動找到執行中的 Scribis,不需要 Port。

bridge.js
{
  "mcpServers": {
    "scribis": {
      "command": "node",
      "args": ["/path/to/mcp_client/bridge.js"]
    }
  }
}
Scribis 使用自訂資料夾時
{
  "mcpServers": {
    "scribis": {
      "command": "node",
      "args": ["/path/to/mcp_client/bridge.js"],
      "env": {
        "SCRIBIS_USER_DATA_PATH": "/path/to/scribis-data"
      }
    }
  }
}
已安裝 CLI 時(第 3 節)
{
  "mcpServers": {
    "scribis": {
      "command": "scribis",
      "args": ["mcp-bridge"]
    }
  }
}
bridge.js 請留在 mcp_client/ 資料夾內:它會載入 cli/ 的程式,單獨複製到別處無法運作。
terminal

3. 安裝 scribis CLI(選用)

CLI 適合在終端機操作,也適合有 shell 權限但沒有原生 MCP 工具的 AI 助手。

安裝 scribis 指令
cd /path/to/mcp_client/cli
node bin/scribis.js install-cli
請將 ~/.local/bin(macOS / Linux)或 %LOCALAPPDATA%\Programs\scribis(Windows,使用者 PATH)加入 PATH。未加入時,請以 node /path/to/mcp_client/cli/bin/scribis.js <command> 執行。Windows 上若該資料夾不在 PATH,直接輸入 scribis 可能會啟動桌面 App 本身。
常用指令
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。

hub

4. 各平台的連線方式

bridge 與 CLI 預設透過本機 Socket 連線,並會自動找到 Scribis。localhost HTTP 端點在所有版本都能使用,所以用 HTTP URL 設定的 MCP Host 不需其他設定。

版本預設(bridge.js、scribis …)備援(localhost HTTP)
WindowsNamed pipe,不需 Porthttp://127.0.0.1:<port>/mcp
scribis … --mcp
macOS(官網下載版)Unix domain socket,不需 Porthttp://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。

macOS / Linux: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 中開啟或匯入該檔案(或將其資料夾加入同步資料夾)。
build

5. 測試與疑難排解

Scribis 開啟且已啟用 MCP 時,執行 scribis status,正常會顯示 Connected。接著可以對 AI 助手說:「用 Scribis 轉錄 ~/Movies/meeting.mp4 並存成 SRT」或「剪掉這段影片的口頭禪和停頓」。

訊息或狀況處理方式
Unable to reach / 連線錯誤開啟 Scribis Desktop,並確認「設定 → MCP協定」已啟用 MCP 伺服器。
Stale MCP discoveryScribis 未正常關閉。請重新啟動 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。