MCPtool server

MCP integration

Use Clipi as a Model Context Protocol (MCP) tool server so AI assistants like Claude, ChatGPT, and other LLM agents can download videos and process media files through natural language.

overview

MCP (Model Context Protocol) is a standard that lets AI assistants interact with external tools. Clipi exposes a set of MCP tools that allow any MCP-compatible client to:

1fetch info

Get video metadata, formats, and thumbnails from any supported URL

2download

Queue a download with specific format, quality, and trimming options

3track progress

Monitor download progress and retrieve the file when ready

4process media

Convert, trim, compress, resize, and edit video, audio, and image files

setup

1. get your API key

Go to My Key and generate an API key. You'll need it for authentication.

2. configure Claude Desktop

Add the following to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "clipi": {
      "command": "npx",
      "args": ["-y", "clipi-mcp"],
      "env": {
        "CLIPI_API_URL": "https://api.clipi.video",
        "CLIPI_API_KEY": "clp_your_api_key_here"
      }
    }
  }
}

3. configure other MCP clients

For other MCP-compatible clients (Cursor, Windsurf, custom agents), use the same npx command with the environment variables:

bash

# Environment variables
CLIPI_API_URL=https://api.clipi.video
CLIPI_API_KEY=clp_your_api_key_here

# Run the MCP server
npx -y clipi-mcp

Tip: The MCP server uses your API key for authentication, so all rate limits and restrictions from your key apply. No additional auth setup required.

available tools

The Clipi MCP server exposes the following tools that AI assistants can call:

video download

tool	description	api endpoint
get_video_info	Fetch video metadata and available formats from a URL	POST /video/info
download_video	Queue a video download with format, quality, and trim options	POST /video/download
get_job_status	Check download progress and get the download URL when ready	GET /jobs/:jobId
get_download_url	Get the direct download link for a completed job	GET /download/:id

media processing tools

Process uploaded files with these tools. Each accepts a file upload plus parameters, returns a jobId for tracking and toolJobId for download.

tool	description	api endpoint
convert_media	Convert video/audio to another format	POST /tools/convert
compress_video	Compress video file size	POST /tools/compress
extract_audio	Extract audio track from video	POST /tools/extract-audio
video_to_gif	Create animated GIF from video clip	POST /tools/gif
generate_thumbnail	Extract a frame as image from video	POST /tools/thumbnail
trim_video	Cut a segment from a video	POST /tools/trim-video
resize_video	Change video dimensions	POST /tools/resize-video
rotate_video	Rotate video 90°/180°/270°	POST /tools/rotate-video
remove_audio	Strip audio from video	POST /tools/remove-audio
change_speed	Speed up or slow down video	POST /tools/video-speed
convert_audio	Convert audio to another format	POST /tools/audio-converter
trim_audio	Cut a segment from audio	POST /tools/trim-audio
convert_image	Convert image format	POST /tools/image-converter
resize_image	Resize image dimensions	POST /tools/resize-image
compress_image	Compress image quality	POST /tools/compress-image
track_tool_job	Track processing progress (SSE)	GET /tools/jobs/:jobId
download_result	Download the processed file	GET /tools/download/:toolJobId

tool schemas

get_video_info

json

{
  "name": "get_video_info",
  "description": "Fetch video metadata and available formats",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "The video URL (YouTube, TikTok, Instagram, Twitter, Vimeo)"
      }
    },
    "required": ["url"]
  }
}

download_video

json

{
  "name": "download_video",
  "description": "Queue a video download job",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "The video URL to download"
      },
      "format": {
        "type": "string",
        "description": "Output format: mp4, webm, mp3, m4a, etc.",
        "default": "mp4"
      },
      "formatId": {
        "type": "string",
        "description": "Specific format ID from get_video_info results"
      },
      "quality": {
        "type": "string",
        "description": "Quality label: 1080p, 720p, 480p, etc."
      },
      "trimStart": {
        "type": "number",
        "description": "Start time in seconds (optional trim)"
      },
      "trimEnd": {
        "type": "number",
        "description": "End time in seconds (optional trim)"
      },
      "noWatermark": {
        "type": "boolean",
        "description": "Remove TikTok watermark if possible"
      }
    },
    "required": ["url"]
  }
}

get_job_status

json

{
  "name": "get_job_status",
  "description": "Check download progress",
  "inputSchema": {
    "type": "object",
    "properties": {
      "jobId": {
        "type": "string",
        "description": "The job ID returned by download_video"
      }
    },
    "required": ["jobId"]
  }
}

media tool schemas (examples)

All tool endpoints use multipart/form-data with a "file" field. Below are key examples:

trim_video

json

{
  "name": "trim_video",
  "description": "Cut a segment from a video file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "file": { "type": "string", "format": "binary", "description": "Video file (multipart upload)" },
      "startTime": { "type": "number", "description": "Start time in seconds" },
      "endTime": { "type": "number", "description": "End time in seconds" }
    },
    "required": ["file", "startTime", "endTime"]
  }
}

generate_thumbnail

json

{
  "name": "generate_thumbnail",
  "description": "Extract a frame from video as image",
  "inputSchema": {
    "type": "object",
    "properties": {
      "file": { "type": "string", "format": "binary" },
      "timestamp": { "type": "number", "description": "Time in seconds (default: 0)" },
      "width": { "type": "number", "description": "Output width (50-3840)" },
      "height": { "type": "number", "description": "Output height (50-2160)" },
      "format": { "type": "string", "enum": ["jpg", "png", "webp"], "default": "jpg" },
      "cropX": { "type": "number", "description": "Crop region X offset" },
      "cropY": { "type": "number", "description": "Crop region Y offset" },
      "cropW": { "type": "number", "description": "Crop region width" },
      "cropH": { "type": "number", "description": "Crop region height" }
    },
    "required": ["file"]
  }
}

change_speed

json

{
  "name": "change_speed",
  "description": "Speed up or slow down a video",
  "inputSchema": {
    "type": "object",
    "properties": {
      "file": { "type": "string", "format": "binary" },
      "speed": { "type": "number", "description": "Speed multiplier (0.25-4)", "default": 1 }
    },
    "required": ["file", "speed"]
  }
}

example prompts

Once configured, you can use natural language to interact with Clipi through your AI assistant:

“Download this YouTube video in 1080p: https://youtube.com/watch?v=dQw4w9WgXcQ”

Claude will fetch info, select the 1080p format, start the download, and give you the link.

“Get the first 30 seconds of this TikTok as mp4: https://tiktok.com/@user/video/123”

Uses trimEnd=30 and noWatermark=true automatically.

“What formats are available for this video? https://vimeo.com/123456”

Calls get_video_info and presents the available formats.

“Extract the audio from this Instagram reel as mp3: https://instagram.com/reel/abc”

Downloads with format=mp3 for audio-only extraction.

“Compress this video to reduce file size: [upload video.mp4]”

Uses compress_video with medium quality to reduce the file size.

“Make a GIF from seconds 5-10 of this video: [upload clip.mp4]”

Calls video_to_gif with startTime=5, duration=5, and optimized palette.

“Generate a thumbnail at the 30 second mark as PNG: [upload movie.mp4]”

Uses generate_thumbnail with timestamp=30, format=png.

“Speed up this video 2x: [upload lecture.mp4]”

Calls change_speed with speed=2 to double the playback rate.

supported platforms

YouTube

youtube.com, youtu.be

TikTok

tiktok.com

Instagram

instagram.com

Twitter / X

twitter.com, x.com

Vimeo

vimeo.com

Others

1000+ sites via yt-dlp