← All guides

Video Processing with Windsurf

Connect FFmpeg Micro to Windsurf via MCP and let Cascade handle video processing tasks. Describe what you need in natural language and Windsurf's AI manages the FFmpeg workflow end to end.

Setup

Add the MCP server to your project's .mcp.json:

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com"
    }
  }
}

Windsurf detects MCP servers from your project config. On the first video processing request, it opens a browser for OAuth sign-in. The token is cached after approval.

Example prompts

  • “Convert this screen recording to a GIF for the README”
  • “Resize this video to 1080p and compress it for web”
  • “Add a title card overlay to the beginning of this demo video”
  • “List all my recent transcode jobs”

Integrated into your flow

Windsurf's Cascade agent can chain video processing with other development tasks. Ask it to process a video, then update your code to reference the new file, or generate thumbnails alongside your build pipeline.

The MCP server accepts public HTTPS URLs, so you can process files from CDNs, cloud storage, or any publicly accessible endpoint without manual uploads.

Troubleshooting

Common problems when running FFmpeg Micro from Windsurf, and what to do about each.

No sign-in window
Sign-in happens in a browser window the first time Windsurf uses the server. If no window opens, check that the server from Setup is saved with the URL https://mcp.ffmpeg-micro.com, exactly as written there.
Request timed out
transcode_and_wait and run_blueprint_and_wait hold the request open until the job is done, and a long render can outlast a 60-second client timeout. Ask Windsurf to start the job and check on it instead: transcode_video then get_transcode, or run_blueprint then get_blueprint_run.
A file on your machine
The tools take URLs. A local file goes up first through request_upload_url and confirm_upload, which hands back the gs:// URL to use as the input.
Download link expired
Download links are signed and short-lived. Ask for a new one and Windsurf calls get_download_url again.
Job failed
Ask Windsurf what went wrong. get_transcode returns the job's error details, for example a file over your plan's size limit or an empty token balance.

Related

Start Free, No Credit Card RequiredMCP setup guide

Want to learn more about what you can build? Explore the FFmpeg API for complete documentation, code examples, and workflows.