# Screen Studio MCP

<p align="center">
  <img src="assets/screenstudio-mcp-hero.png" alt="Screen Studio MCP: an agent that shoots and edits your videos." width="100%">
</p>

<p align="center">
  <strong>An agent that shoots and edits your videos.</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/screenstudio-mcp"><img alt="npm" src="https://img.shields.io/npm/v/screenstudio-mcp?style=flat-square&color=684cff"></a>
  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-071236?style=flat-square"></a>
  <img alt="macOS" src="https://img.shields.io/badge/macOS-Screen%20Studio%204-684cff?style=flat-square">
</p>

Screen Studio MCP lets Claude Code or Codex make a real video in [Screen Studio](https://screen.studio). It uses your app with real clicks and taps, records it, reads the footage, cuts it with editing rules about pacing, adds voice, captions and music, and exports every size you need. Every edit happens live in the Screen Studio editor, on your screen, with the app's own undo.

Unofficial. Not affiliated with Screen Studio.

## Start Here

Run one command:

```bash
npx screenstudio-mcp
```

It installs the MCP server and three skills (record, edit, deliver) into Claude Code and Codex, then checks your Mac. Restart your agent and ask:

```text
Record a 30-second demo of my app's onboarding and edit it in Screen Studio.
```

In Claude Code you can also install it as a plugin:

```text
/plugin marketplace add tolimarchuk/screenstudio-mcp
/plugin install screenstudio@screenstudio-mcp
```

## See It Work

<table>
  <tr>
    <td width="50%"><a href="assets/demo-trailer.mp4"><img src="assets/demo-trailer.png" alt="A launch trailer for an iPhone game, shot and edited by the agent."></a></td>
    <td width="50%"><a href="assets/how-it-works.mp4"><img src="assets/how-it-works.png" alt="How it works, explained 3Blue1Brown style."></a></td>
  </tr>
  <tr>
    <td><strong>The trailer.</strong> One prompt. The agent played a game with real taps, timed rhythm taps to the music, voiced it and cut 96 seconds down to 41.</td>
    <td><strong>How it works.</strong> Hands, eyes and taste, and why every cut bends time.</td>
  </tr>
</table>

## How It Thinks

```text
Hands -> Eyes -> Taste -> Live
```

**Hands.** The agent uses your app the way a person would: the pointer glides and settles before it clicks, text types at a readable rhythm, and a beat records as one take with markers. It can tap in bursts and press and hold, so games and press-and-hold UI work too.

**Eyes.** After the take, it reads the recording as data: every click, keystroke, screen change, pause and spoken word. Ninety seconds of footage becomes a list of moments, each one scored.

**Taste.** Good editing is mostly rules about time. Hold every result long enough to read it. Cut the dead air. Never zoom faster than the eye can settle. A tutorial cuts about every ten seconds; a launch trailer cuts on every beat. The planner explains each cut, speed-up and zoom in plain words, and a pacing check catches anything too fast before you export.

**Live.** The edit plays out in the real Screen Studio editor: the playhead jumps, clips get chopped, zooms drop in, panels open as settings change. Cmd+Z works.

Voiceover lines are pinned to moments in the recording, not the video, so a line still lands on its moment after you re-cut ten times.

## Recipes

One word sets the whole direction. None is a default.

| Recipe | For |
|---|---|
| `social-vertical` | A 9:16 clip for a vertical feed, under 30 seconds, captions and a big cursor. |
| `launch-teaser` | A 20-second teaser: only the best beats, the payoff saved for last. |
| `keynote` | A product moment for a big screen or a launch page: unhurried and premium. |
| `changelog` | One shipped feature in under 45 seconds, quiet, one or two zooms on what changed. |
| `tutorial` | Step by step: calm holds, shortcuts on screen, a chapter per marker. |
| `founder-talking-head` | You on camera, cut out beside the screen, pauses and fillers trimmed. |
| `docs-walkthrough` | A silent clip for documentation, slow enough to follow along. |

Save your own colors, cursor and voice as a brand kit and it goes on top of any recipe.

## What It Can Do

- **Record** any window, display or area, with system audio, microphone and camera.
- **Drive apps** with native clicks, typing, scrolling, drags, taps and holds.
- **Analyze** footage: clicks, typing, scene changes, idle time, transcripts and fillers.
- **Plan and edit** cuts, speed-ups, zooms, the glass loupe, camera layouts, masks, crop, backdrop, cursor and every other Screen Studio setting.
- **Voice** narration with a neural voice, add captions, and lay library music ducked under speech.
- **Deliver** variants for X, Shorts, LinkedIn, landing pages and docs, seamless loops, contact sheets, chapters and captions files.
- **Protect** you: find keys, emails and other private text on screen and blur them before you publish.

46 tools in all. Each guide the skills use is also served as a `screenstudio://` resource.

## Requirements

- macOS with [Screen Studio](https://screen.studio) 4 (tested on 4.0.1-4897). Turn off Screen Studio's auto-update once it works. Reading footage works on any 4.x build. To record and edit on an untested build, set `SCREENSTUDIO_ALLOW_UNTESTED=1`.
- Node 22 or newer.
- `ffmpeg` and `ffprobe`: `brew install ffmpeg`.
- For narration, `edge-tts`: `pipx install edge-tts`.
- Accessibility and Screen Recording permission for the app you run your agent in (Terminal, Claude, Codex). `npx screenstudio-mcp doctor` asks macOS for both and checks everything else.

## Safety

- **Your mouse wins.** Input stops the moment you move the mouse or click another window, and the helper lets go of any held key or button.
- **Off limits by default.** Terminals, password managers and System Settings can't be clicked, typed into or screenshotted. Name an app in `SCREENSTUDIO_ALLOW_APPS` to record it anyway. System shortcuts like Spotlight, the app switcher and quit are never sent.
- **Local only.** The server talks to Screen Studio over a debugging connection bound to 127.0.0.1, and only to Screen Studio's own pages. While Screen Studio runs with it open, other programs on your Mac could connect too, so quit Screen Studio (or call `screenstudio_quit`) when you're done.
- **Nothing is lost.** Every edit batch saves a checkpoint you can restore, and the app's undo works. Exports never overwrite a file. The app is never killed or restarted.
- **What leaves your Mac.** Narration sends each line's text to Microsoft's online speech service (edge-tts). Nothing else does.

## Commands

```bash
npx screenstudio-mcp              # install into Claude Code and Codex, then check this Mac
npx screenstudio-mcp doctor       # check Screen Studio, ffmpeg, permissions
npx screenstudio-mcp@latest update  # move to the newest version
npx screenstudio-mcp uninstall    # remove the server and skills
```

<details>
<summary>Manual setup and configuration</summary>

Claude Code:

```bash
claude mcp add -s user screenstudio -- npx -y screenstudio-mcp serve
```

Codex, in `~/.codex/config.toml`:

```toml
[mcp_servers.screenstudio]
command = "npx"
args = ["-y", "screenstudio-mcp", "serve"]
tool_timeout_sec = 1800
```

| Variable | What it does |
|---|---|
| `SCREENSTUDIO_APP_PATH` | Where Screen Studio is, if not in Applications. |
| `SCREENSTUDIO_PORT` | A fixed automation port instead of a free one. |
| `SCREENSTUDIO_STATE_DIR` | Where checkpoints, caches and brand kits live (default `~/.screenstudio-mcp`). |
| `SCREENSTUDIO_ALLOW_UNTESTED` | `1` lets recording and editing run on an untested 4.x build. |
| `SCREENSTUDIO_ALLOW_APPS` | Bundle ids the agent may drive even though they are off limits, comma separated. |
| `SCREENSTUDIO_FFMPEG`, `SCREENSTUDIO_FFPROBE`, `SCREENSTUDIO_EDGE_TTS` | Paths to those tools. |

</details>

## For This Repo

The package ships the native input helper prebuilt for Apple Silicon and Intel, built from [native/Desktop.swift](native/Desktop.swift) on GitHub Actions and published with npm provenance. See [CONTRIBUTING.md](CONTRIBUTING.md) to build from source, [docs/architecture.md](docs/architecture.md) for how it fits together and [docs/compatibility.md](docs/compatibility.md) for what a new Screen Studio version needs. Release history is in the [changelog](CHANGELOG.md).

Builds on [screenstudio-cli](https://github.com/ShawnPana/screenstudio-cli) by Shawn Pana and [screenstudio-agent](https://github.com/HyperfocuSam/screenstudio-agent) by Sam Wong.

## Star History

<a href="https://www.star-history.com/?repos=tolimarchuk%2Fscreenstudio-mcp&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=tolimarchuk/screenstudio-mcp&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=tolimarchuk/screenstudio-mcp&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=tolimarchuk/screenstudio-mcp&type=date&legend=top-left" />
 </picture>
</a>

## License

MIT