Model Context Protocol & AI Agent Skills

Scribis AI Agent Skills & MCP Integration Guide

Connect Claude Code, Claude Desktop, Cursor, OpenAI Codex, Google Antigravity, Windsurf and other MCP hosts to Scribis Desktop. Your AI assistant can then transcribe locally, fix subtitles, rough-cut, add motion graphics, music and voice-overs inside the running app.

downloadDownload scribis.install-skill.zip

The ZIP contains one folder, mcp_client/, with the 11 Agent Skills, bridge.js, the scribis CLI and a demo client. Move it somewhere permanent; the examples below call it /path/to/mcp_client. On macOS, ignore a __MACOSX/ folder if your unzip tool creates one.

checklistBefore you start

  • Scribis Desktop is installed and running.
  • MCP is enabled in Settings → MCP Protocol. That page shows the active port (default 8890) and ready-to-copy snippets for each host.
  • Node.js 18 or later, only for bridge.js, the scribis CLI and the demo client. The bridge and CLI have no dependencies, so no npm install is needed.
psychology

1. Install the Agent Skills

The skills teach your AI assistant how to use Scribis. Copy every skills/scribis-* folder into your agent's skills directory.

scribis-transcribe

Core skill: transcription, subtitles/SRT, live speech-to-text, rough cuts, zooms, mosaics, scenes, TTS, frame previews and the scribis CLI.

scribis-edit

Commands copied from Scribis (/scribis-edit cuts <id>, /scribis-edit scene <id>): opens that editor and routes the request.

scribis-motion

Animated titles, charts of your numbers, callouts, lower thirds and other HTML motion graphics, plus single-detail changes.

scribis-audio

Background music and sound effects: library search, import, generated effects, fades, ducking under speech and loudness checks.

scribis-voice

Voice-overs (TTS), re-voicing a line in a speaker's own or cloned voice, and timing animation to the spoken words.

scribis-explainer

Short animated explainers and data stories built as a scene of editable beats from a report, numbers or a YouTube video.

scribis-earshot

Listening checks: whether a sound matches its description, sound labels, finding moments in a recording, and loudness and peak measurements, with models that run locally.

scribis-writing

Research, narration and script drafting, revision, summaries and translation from briefs, articles or Scribis transcripts; writing alone needs no app connection.

scribis-color

Automatic colour grading of scenes: measured exposure and white-balance fixes, shot matching to a reference clip, and creative looks.

scribis-storyboard

Storyboards a script and its media folder, writes a style-aware motion graphic for each group of beats, and reviews the frames before you accept them in the scene editor.

scribis-2d-video

Script-to-video stories as editable HTML shots with narration, subtitles, music and effects: stick figures, a watercolour storybook, or any Scribis motion style.

Install all the skills together, side by side. They link to each other with relative paths, so a skill installed on its own has broken links.
AgentProject (one repository)Personal (all projects)
Claude Code.claude/skills/~/.claude/skills/
OpenAI Codex.agents/skills/~/.agents/skills/
Google Antigravity.agents/skills/~/.gemini/config/skills/older versions: ~/.gemini/antigravity/skills/
Cursor.cursor/skills/ · .agents/skills/~/.cursor/skills/ · ~/.agents/skills/
Windsurf.windsurf/skills/ · .agents/skills/~/.codeium/windsurf/skills/ · ~/.agents/skills/
Other Agent Skills hosts.agents/skills/~/.agents/skills/
Example: Claude Code on macOS / Linux
mkdir -p ~/.claude/skills
cp -R /path/to/mcp_client/skills/scribis-* ~/.claude/skills/
Example: Claude Code on Windows (PowerShell)
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 also reads .claude/skills/, so one Claude Code install covers both. Skill locations can change between host versions; if a skill is not picked up, check your host's documentation. Restart the agent (or start a new session) after installing.

💡 In Scribis, the copy button next to Open in Cuts → Recent edits and Scenes copies /scribis-edit cuts <id> or /scribis-edit scene <id>. Paste it into your AI agent and the scribis-edit skill opens that project and starts working on it.
settings_ethernet

2. Connect Scribis to Your MCP Host

Most hosts connect directly to the Scribis MCP endpoint over localhost HTTP. Replace <port> with the port shown in Settings → MCP Protocol (default 8890).

HostConfig fileSnippet
Claude Code.mcp.json{"mcpServers": {"scribis": {"type": "http", "url": "http://127.0.0.1:<port>/mcp"}}}Keep "type": "http": an entry without it is read as a stdio server.
Claude Desktopclaude_desktop_config.jsonstdio only: use bridge.js (below).
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 requires serverUrl.
Windsurfmcp_config.json{"mcpServers": {"scribis": {"serverUrl": "http://127.0.0.1:<port>/mcp"}}}url is also accepted.
Other Agent Skills hostsmcp.json{"mcpServers": {"scribis": {"url": "http://127.0.0.1:<port>/mcp"}}}Or use the stdio bridge below.
Claude Code can also add it from the terminal:
claude mcp add --transport http scribis http://127.0.0.1:8890/mcp

stdio hosts: bridge.js

Hosts that can only start a local process (such as Claude Desktop) use bridge.js. It finds the running Scribis app automatically and needs no port.

bridge.js
{
  "mcpServers": {
    "scribis": {
      "command": "node",
      "args": ["/path/to/mcp_client/bridge.js"]
    }
  }
}
Scribis uses a custom data folder
{
  "mcpServers": {
    "scribis": {
      "command": "node",
      "args": ["/path/to/mcp_client/bridge.js"],
      "env": {
        "SCRIBIS_USER_DATA_PATH": "/path/to/scribis-data"
      }
    }
  }
}
With the CLI installed (section 3)
{
  "mcpServers": {
    "scribis": {
      "command": "scribis",
      "args": ["mcp-bridge"]
    }
  }
}
Keep bridge.js inside the mcp_client/ folder: it loads code from cli/, so it does not work when copied elsewhere on its own.
terminal

3. Install the scribis CLI (Optional)

The CLI is useful in the terminal and for agents that have shell access but no native MCP tools.

Install the scribis command
cd /path/to/mcp_client/cli
node bin/scribis.js install-cli
Add ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\scribis (Windows, user PATH) to your PATH. Without it, run node /path/to/mcp_client/cli/bin/scribis.js <command>. On Windows a bare scribis may start the desktop app itself when that folder is not on PATH.
Common commands
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

The CLI never downloads models: run scribis models first and download missing models in Settings → Models. Commands exit with code 1 on failure.

hub

4. Connection Modes by Platform

The bridge and the CLI talk to Scribis over a local socket by default and find it automatically. The localhost HTTP endpoint works on every build, so MCP hosts configured with the HTTP URL need nothing else.

BuildDefault (bridge.js, scribis …)Fallback (localhost HTTP)
WindowsNamed pipe, no port neededhttp://127.0.0.1:<port>/mcp
scribis … --mcp
macOS (direct download)Unix domain socket, no port neededhttp://127.0.0.1:<port>/mcp
scribis … --mcp
macOS (Mac App Store)Unix domain socket in the Scribis app group container, found automaticallyhttp://127.0.0.1:<port>/mcp
scribis … --mcp

Using --mcp (HTTP) with the CLI

Add --mcp to any CLI command to use localhost HTTP. The CLI reads the port the running app publishes; set SCRIBIS_MCP_PORT only to force a 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 build

  • The first time a terminal or MCP host reads the Scribis app group container, macOS may ask whether it can access data from other apps. Allow it so the bridge and CLI can find Scribis.
  • If scribis status reports "stdio socket is unavailable", switch to HTTP: use scribis … --mcp or the http://127.0.0.1:<port>/mcp URL. The error message shows the port.
  • Scribis can only read files you have granted it. If a tool cannot read a file, open or import it in Scribis first (or add its folder as a synced folder).
build

5. Test & Troubleshoot

With Scribis running and MCP enabled, run scribis status: a healthy run prints Connected. Then ask your assistant something like "Transcribe ~/Movies/meeting.mp4 with Scribis and save an SRT".

Message or symptomWhat to do
Unable to reach / connection errorOpen Scribis Desktop and make sure the MCP server is on in Settings → MCP Protocol.
Stale MCP discoveryScribis was closed without cleaning up. Restart Scribis, or turn the MCP server off and on in Settings.
stdio socket is unavailableUse HTTP instead: scribis … --mcp, or the http://127.0.0.1:<port>/mcp URL in your MCP host.
--mcp reports no portSet SCRIBIS_MCP_PORT to the port shown in Settings → MCP Protocol.
Skills not picked upCheck the skills folder for your host and version, keep all the scribis-* folders side by side, and start a new agent session.
Model not installedRun scribis models, then download the model in Settings → Models.
Custom Scribis data folderSet SCRIBIS_USER_DATA_PATH (or SCRIBIS_DISCOVERY_PATH / SCRIBIS_SOCKET_PATH) for the bridge and CLI.

shieldSecurity

  • The MCP endpoint only accepts connections from your own computer (127.0.0.1, localhost, [::1]). Requests from websites and other hosts are rejected, and no token is needed.
  • Scribis also offers an OpenAI-compatible REST API (/v1) on the same port, protected by API keys you create in Settings → MCP Protocol. Read README.md in the package before exposing it outside your computer.