# ScreenSlick MCP install guide

Last updated: 2026-06-18

ScreenSlick ships with a local MCP server for agent-driven video editing. The MCP client launches the `screenslick-mcp` npm package over stdio. That package opens a localhost WebSocket bridge at `127.0.0.1:32117/screenslick-agent`, and the browser editor connects when the Agent button is enabled.

## Prerequisites

- Install Node.js.
- Open ScreenSlick in your browser.
- Click the editor Agent button and wait for it to show connected.

## Shared stdio values

- Name: `screenslick`
- Transport: `stdio`
- Command: `npx`
- Arguments: `-y, screenslick-mcp`
- Requires ScreenSlick repo: `No`

Optional environment variables:

- `SCREEN_SLICK_AGENT_PORT`: override bridge port `32117`
- `SCREEN_SLICK_AGENT_HOST`: override bridge host `127.0.0.1`

## Codex Desktop

Use the custom MCP form with STDIO selected.

- Open Codex settings.
- Choose Connect to a custom MCP.
- Select STDIO.
- Set Name to screenslick.
- Set Command to npx.
- Add arguments: -y, screenslick-mcp.
- Save, open a new thread, and ask for screenslick_bridge_status.

## Codex CLI

Add a stdio server entry to the Codex config.

```toml
[mcp_servers.screenslick]
command = "npx"
args = ["-y", "screenslick-mcp"]
startup_timeout_sec = 10
tool_timeout_sec = 120
```

- Add the TOML block to your Codex config.
- Restart Codex.
- Open the ScreenSlick editor and click Agent.
- Call screenslick_bridge_status.

## Claude Code

Use project-scoped .mcp.json in any project you want Claude Code to edit from.

```json
{
  "mcpServers": {
    "screenslick": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "screenslick-mcp"]
    }
  }
}
```

- Create .mcp.json in the project where you use Claude Code.
- Restart Claude Code.
- Approve the project-scoped server when prompted.
- Run /mcp and confirm screenslick is connected.

## Claude Desktop

Add screenslick to claude_desktop_config.json.

```json
{
  "mcpServers": {
    "screenslick": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "screenslick-mcp"]
    }
  }
}
```

- Open Settings > Developer > Edit Config.
- On macOS, the file is ~/Library/Application Support/Claude/claude_desktop_config.json.
- On Windows, the file is %APPDATA%\Claude\claude_desktop_config.json.
- Add the JSON config and restart Claude Desktop.
- Confirm the server appears as a connector.

## Cursor

Use .cursor/mcp.json or Settings > Tools & MCP.

```json
{
  "mcpServers": {
    "screenslick": {
      "command": "npx",
      "args": ["-y", "screenslick-mcp"]
    }
  }
}
```

- Create .cursor/mcp.json for project config, or ~/.cursor/mcp.json for global config.
- Paste the JSON config.
- Reload Cursor or refresh Tools & MCP.
- Confirm screenslick is enabled and its tools are visible.

## Generic MCP clients

Use local stdio transport with the shared launch values.

```json
{
  "mcpServers": {
    "screenslick": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "screenslick-mcp"]
    }
  }
}
```

- Choose stdio transport.
- Use npx as the command.
- Pass -y, screenslick-mcp as args.
- No working directory is required.

## Development mode

Only use this when working on the ScreenSlick source repo itself:

```json
{
  "mcpServers": {
    "screenslick-dev": {
      "type": "stdio",
      "command": "node",
      "args": ["--import", "tsx", "scripts/screenslick-agent-mcp.ts"],
      "cwd": "/path/to/screenslick"
    }
  }
}
```

## Verify

Ask the agent to call `screenslick_bridge_status`. A healthy response has `ok: true`, `connected: true`, `port: 32117`, `path: "/screenslick-agent"`, and a `session` object.

Useful follow-up checks:

- `screenslick_bridge_status`
- `screenslick_health_check`
- `screenslick_get_project`

## Available tools

- `screenslick_bridge_status`
- `screenslick_health_check`
- `screenslick_get_project`
- `screenslick_get_capabilities`
- `screenslick_list_voices`
- `screenslick_review_director_draft`
- `screenslick_validate_voiceover_timing`
- `screenslick_analyze_video_segments`
- `screenslick_find_clip_candidates`
- `screenslick_create_clip_collection`
- `screenslick_remove_silences`
- `screenslick_generate_transcript`
- `screenslick_apply_commands`
- `screenslick_generate_script`
- `screenslick_director_plan`
- `screenslick_create_demo_video`
- `screenslick_generate_voiceover`
- `screenslick_add_transcript_voiceover_to_timeline`
- `screenslick_clear_voiceover`
- `screenslick_replace_voiceover_clips`
- `screenslick_update_voiceover_clip`
- `screenslick_move_voiceover_clip`
- `screenslick_delete_voiceover_clip`
- `screenslick_regenerate_voiceover_clip`
- `screenslick_extract_on_screen_captions`
- `screenslick_merge_on_screen_caption_ocr`
- `screenslick_create_voiceover_from_on_screen_captions`
- `screenslick_preview_voiceover`
- `screenslick_toggle_voiceover`
- `screenslick_cleanup_timeline`
- `screenslick_capture_frame`
- `screenslick_export_video`

## Common prompts

- Remove silence segments, add a 10% padded background, generate local transcripts, and add an intro text that says "ScreenSlick MCP server".
- Generate a short narration script, add it as editable timeline voiceover clips, use a local friendly voice, then preview the voiceover.
- Clear the existing voiceover, extract the on-screen text, and rebuild narration as timeline voiceover clips.
- Sample the baked-in captions between 2:50 and 3:30, OCR the returned crops, then rebuild those voiceover clips with corrected timing.
- Create a Director Mode plan for a high-energy product demo with captions, music, intro, outro, and voiceover.
- Dry-run a Director Mode first draft with intro/outro text, a colorful background, music, and subtle motion.
- Find three strong Shorts candidates from this long explainer and return the ranges with reasons.
- Validate the voiceover timing and tell me where there are overlaps, long gaps, or duplicate lines.
- Add clip section transitions with tilt, entry/exit animation, and subtle whoosh sound effects.

## Troubleshooting

- If tools are missing, restart the agent client after adding the MCP server.
- If tools exist but fail, confirm the editor Agent button says connected.
- If the port is busy, set SCREEN_SLICK_AGENT_PORT in the MCP server environment and use the same port in the editor bridge URL.
- If the server starts and then disconnects, check .tmp/screenslick-agent-mcp.log.
- If the client cannot launch the server, run npx -y screenslick-mcp from a normal terminal and inspect the terminal error.