chatcut-mcp-server 0.2.1

Model Context Protocol (MCP) server for local video editing, presentation overlays, transcription, and hardware-accelerated rendering.

ChatCut MCP Server 🎬🤖

ChatCut MCP Server is a Model Context Protocol (MCP) server that empowers AI coding agents (such as Claude Code, Cursor, Codex, or Antigravity) with local video editing, media processing, transcription, and hardware-accelerated rendering capabilities.

With this server, you can give your AI agent natural language instructions like "trim the silences from this video, overlay slide 2 at second 20, and render it using my GPU" or "transcribe this video, find the most engaging segment, and create a vertical 9:16 Short", and the agent will know exactly which tools to call to physically process the video on your local machine.

---

🛠️ Tools Reference

The server automatically registers the following tools with the MCP client:

Tool Name	Arguments	Description
detect_hardware	None	Auto-detects the system's active GPU (NVIDIA, Apple Silicon, Intel, AMD) and checks if FFmpeg has hardware encoders enabled.
parse_video_guidelines_excel	file_path: str	Parses an Excel video editing guidelines file and outputs the cut ranges and slide overlay times in seconds.
convert_pptx	pptx_path: str, output_dir: str	Converts a PowerPoint presentation to PNG slides and pre-scales them to $1920 \times 1080$ in a cache directory (significantly speeds up FFmpeg rendering).
transcribe_video_file	video_path: str, gemini_api_key: str (optional), force_local: bool (optional)	Transcribes a video file to JSON with timestamps. Uses the Gemini API (cloud-based, free/fast) or local Whisper (faster-whisper running on CPU or GPU).
find_short_clips	transcript_json: str, gemini_api_key: str (optional)	Analyzes the transcript text and identifies the 3 best 30-60 second clips for vertical Shorts/Reels/TikToks with hook explanations.
generate_vertical_crop_timeline	timeline_json_path: str, start_time: float, end_time: float, crop_type: str (optional)	Creates a vertical (9:16) 1080x1920 timeline configuration, cropping or fitting the main video for the specified time segment.
render_video_project	timeline_json_path: str, output_mp4_path: str	Renders the final video from the timeline configuration using FFmpeg with GPU-accelerated encoding (e.g. -c:v h264_nvenc).

---

🤖 INSTRUCTIONS FOR AI AGENTS (Claude Code / Codex / Antigravity)

If you are an AI agent reading this repository and the user has asked you to "Install this MCP server", follow these steps based on the user's operating system:

Step 1: Check System Dependencies

Ensure the user's system has python (>= 3.10), ffmpeg, and optionally libreoffice (required for .pptx conversions) installed. If they are missing, inform the user or request permission to install them.

Step 2: Locate the MCP Client Configuration File

Locate the configuration file corresponding to the application the user is using to converse with you:

• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json
• Claude Code (Global CLI): ~/.claude.json
• Cursor (IDE): Configurable in the Settings -> Features -> MCP section of the graphical interface.

Step 3: Add the Server to Configuration

Read the configuration JSON file and append a new entry under the "mcpServers" key.

Option A: Install from PyPI (Recommended for production)

"chatcut": {
  "command": "uvx",
  "args": ["chatcut-mcp-server"],
  "env": {
    "GEMINI_API_KEY": "YOUR_OPTIONAL_API_KEY"
  }
}

Option B: Install from Local Source (Recommended for development/WSL)

"chatcut-local": {
  "command": "wsl",
  "args": [
    "-d", "Ubuntu",
    "-u", "parrot",
    "bash", "-c",
    "cd /home/parrot/video && venv/bin/chatcut-mcp-server"
  ],
  "env": {
    "GEMINI_API_KEY": "YOUR_OPTIONAL_API_KEY"
  }
}

Write the configuration back, preserving all other existing keys.

---

👨‍💻 HUMAN INSTALLATION GUIDE

Option A: Automatic Running (Recommended)

If you have uv installed on your system, you can run the server instantly without a permanent installation using uvx:

uvx chatcut-mcp-server

Option B: Local Source Installation

1. Clone the repository:

   git clone [e-mail]:madrigal-a/chatcut-mcp-server.git
   cd chatcut-mcp-server
   

2. Create a virtual environment and install the package in editable mode:

   python -m venv venv
   source venv/bin/activate  # On Windows use: venv\Scripts\activate
   pip install -e .
   

3. Run the server:

   chatcut-mcp-server
   

---

📝 Additional System Requirements

• LibreOffice headless: Required for automated PPTX to PDF conversions. On Ubuntu, install it using sudo apt-get install libreoffice.
• Poppler-utils: Required by pdf2image to extract pages from PDF files. On Ubuntu, install it using sudo apt-get install poppler-utils.