File Conversion MCP Server: Plug FFmpeg Into Claude Code

TL;DR: - Convert any file format inside Claude Code by exposing a remote FFmpeg API as an MCP tool—no local ffmpeg binary to install or maintain - Model Context Protocol (MCP) crossed 10,000 public servers in early 2026; file conversion is still an underserved tool category - This guide ships a ready-to-use mcp-config.json you can paste into Claude Code or Cursor Cloud Agent in under 5 minutes - Works for PDFs, Office docs, images, audio, and video—anything FFmpeg handles

You need to convert a 500MB ProRes file to H.264, or turn a Word doc into a clean PDF, or extract audio from a video clip. Your Claude Code agent says "I can't do that" because it has no file conversion tools. You could install FFmpeg locally, manage codecs, and debug libx264 presets. Or you could give your agent one tool call that handles the entire pipeline on a managed API. This article shows the second path. It is for developers and automation builders who want their AI agents to manipulate files as naturally as they manipulate text.

---

What Is an MCP Server and Why Does It Need FFmpeg?

An MCP server is a lightweight bridge that lets AI assistants like Claude Code call external tools through a standardized protocol. Think of it as a USB-C port for AI capabilities: one spec, any tool. Anthropic open-sourced MCP in November 2024. By mid-2026, developers had published over 10,000 public servers, per Anthropic's developer blog. Yet file conversion—one of the most common automation tasks—remains poorly represented.

Most MCP tutorials focus on web search, database queries, or code execution. File conversion is harder because it requires binary processing, format detection, and often large file handling. FFmpeg is the de facto standard for this work, but running it inside an AI agent's environment introduces dependency hell. An MCP server that wraps a remote FFmpeg API solves this: the agent sends a file, the API converts it, the agent receives the result.

---

How FFmpeg File Conversion Works Over an API

FFmpeg converts media by reading input files, applying filters and codecs, and writing output files. When exposed through an API, this same process happens on remote servers. Your agent sends an HTTP request with the source file and desired format; the API handles the FFmpeg command, streaming, and error handling.

The typical flow looks like this:

1. Upload — Client sends file to API storage (presigned URL or direct multipart upload)
2. Queue — API assigns a job ID and spins up an FFmpeg process
3. Process — FFmpeg executes the conversion with specified codecs, bitrate, resolution
4. Deliver — API returns a download URL or pushes to webhook

For AI agents, this becomes even simpler. The MCP server abstracts steps 1–4 into a single convert_file tool that accepts source_url, target_format, and optional parameters like quality or resolution.

---

Build vs. Buy: Local FFmpeg, Cloud API, or Managed Service?

Developers face three real options for adding file conversion to their agent workflows. Each has distinct trade-offs in control, cost, and operational burden.

The honest trade-off: local FFmpeg gives you maximum control but consumes time you could spend building your actual product. Self-hosted solutions look cheap until you price engineer hours for security patches and scaling. A managed API converts capital expense into predictable operational cost. For AI agent workflows—where the goal is to remove friction, not add infrastructure—the managed route usually wins.

---

Step-by-Step: Connect ConvertFleet to Claude Code via MCP

You can expose any file conversion API as an MCP tool by writing a small server wrapper. Below is the complete setup for connecting ConvertFleet's API to Claude Code. The same pattern applies to Cursor Cloud Agent or any other MCP client.

Prerequisites

• Claude Code installed and authenticated (claude --version returns 0.32 or higher)
• A ConvertFleet API key (free tier available)
• Node.js 18+ installed locally

Step 1: Create the MCP Server File

Create a new directory and initialize:

mkdir claude-convertfleet-mcp
cd claude-convertfleet-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod

Create index.js:

#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const CONVERTFLEET_API = 'https://api.convertfleet.com/v1';
const API_KEY = process.env.CONVERTFLEET_API_KEY;

if (!API_KEY) {
  console.error('CONVERTFLEET_API_KEY required');
  process.exit(1);
}

const server = new Server(
  { name: 'convertfleet-converter', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'convert_file',
    description: 'Convert a file from one format to another using FFmpeg. Supports video, audio, images, PDFs, and Office documents.',
    inputSchema: {
      type: 'object',
      properties: {
        source_url: { type: 'string', description: 'Public URL of the file to convert' },
        target_format: { type: 'string', description: 'Desired output format, e.g. mp4, mp3, pdf, png' },
        quality: { type: 'string', enum: ['low', 'medium', 'high'], default: 'medium' }
      },
      required: ['source_url', 'target_format']
    }
  }]
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name !== 'convert_file') {
    throw new Error(`Unknown tool: ${request.params.name}`);
  }

  const { source_url, target_format, quality } = request.params.arguments;

  const response = await fetch(`${CONVERTFLEET_API}/convert`, {
    method: 'POST',
    headers: { 
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ source_url, target_format, quality })
  });

  if (!response.ok) {
    throw new Error(`ConvertFleet API error: ${response.status} ${await response.text()}`);
  }

  const result = await response.json();
  return { content: [{ type: 'text', text: `Conversion started. Job ID: ${result.job_id}. Download: ${result.download_url}` }] };
});

const transport = new StdioServerTransport();
await server.connect(transport);

Step 2: Configure Claude Code to Use Your Server

Add to your Claude Code configuration (typically ~/.claude/mcp-config.json or via claude mcp add):

{
  "mcpServers": {
    "convertfleet": {
      "command": "node",
      "args": ["/absolute/path/to/claude-convertfleet-mcp/index.js"],
      "env": {
        "CONVERTFLEET_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Code. Run claude mcp list to verify the server appears.

Step 3: Use It in Conversation

With a file conversion MCP server connected, your agent gains a new capability. Try:

"Convert this video to audio: https://example.com/interview.mp4 → mp3"

Or:

"Turn this Word document into a PDF: https://example.com/report.docx"

The agent calls your convert_file tool, polls for completion, and returns the download link. No FFmpeg command line knowledge required. No local binary to debug.

Grab the ready-to-use MCP config JSON in the free download below—validated structure, just add your API key.

---

What File Formats Can You Convert Through an MCP Tool?

The full ConvertFleet API supports 178+ formats across six categories. Your MCP server inherits this breadth automatically. Here is what that means in practice:

A common mistake: assuming "FFmpeg" means only video and audio. The underlying tools handle far more. When you expose the full API through MCP, your agent can work with any file a user throws at it.

---

Common Mistakes When Building File Conversion MCP Tools

The fastest way to waste an afternoon is skipping error handling for large files. Here are the gotchas that break production MCP servers:

Mistake 1: Blocking the main thread on uploads FFmpeg conversions on large files take time. If your MCP server waits synchronously, Claude Code times out after 30 seconds. Always return a job ID immediately and let the agent poll or use webhooks.

Mistake 2: Ignoring format-specific parameters A video conversion to MP4 needs codec hints. A PDF to Word conversion needs layout preservation flags. Expose these as optional parameters in your tool schema, or the agent will make poor defaults.

Mistake 3: Hardcoding authentication Never put API keys in the server code. Use environment variables, as shown above, so the same server works across dev, staging, and production without changes.

Mistake 4: Forgetting rate limits ConvertFleet's free tier handles generous volume, but any API has limits. Return clear error messages the agent can relay: "Rate limited. Retry after 60 seconds or upgrade at /pricing."

---

How This Compares to Other File Conversion Workflows

Developers familiar with n8n automation might wonder when to use MCP instead. The answer depends on who initiates the action.

The MCP approach shines when a human and AI collaborate. You describe what you want in plain language; the agent handles the mechanics. For overnight batch jobs processing thousands of files, n8n still wins. Many teams use both: MCP for agent-assisted exploration, n8n for production pipelines. See our n8n RAG workflow guide for how file conversion fits into larger document processing systems.

---

Extending the MCP Server for Your Stack

The basic server above handles single-file conversion. Production use demands more.

Add these capabilities incrementally:

1. Batch conversion — Accept an array of source_urls and return a zip of results
2. Progress streaming — Use MCP's notifications/progress to show conversion status
3. Format detection — Auto-detect source format from bytes or URL when not specified
4. Webhook callbacks — Push results to a user-provided URL instead of polling

Each extension follows the same pattern: expand the Zod schema, validate inputs, call the ConvertFleet API, format the response. The MCP protocol handles the rest.

---

Free download

To make this actionable, we built a free resource you can grab right now — no signup:

• ⬇ N8N Workflow: ffmpeg-file-conversion-workflow-79a2dbc2cce25a1f.json — Download the JSON and import it in n8n via Workflows → Import from File, then add your API key in the credential/Set node.

Frequently Asked Questions

What is file conversion? File conversion is the process of changing a file from one digital format to another—such as turning a Word document into a PDF, or a WAV audio file into an MP3—while preserving as much of the original content and quality as possible.

How do I convert files online? Upload your file to a conversion service or API, select the target format, and download the result. With an MCP server connected to Claude Code, you simply describe the conversion in natural language and the agent handles the upload, processing, and retrieval automatically.

What is the best file conversion software? For developers and automation builders, the best solution depends on workflow integration. FFmpeg remains the underlying engine for most conversions. Managed APIs like ConvertFleet wrap FFmpeg with modern interfaces—REST, n8n nodes, or MCP tools—removing the need to compile binaries or manage servers.

Can I convert files for free? Yes. ConvertFleet offers a free tier with generous monthly limits suitable for personal projects and development. For production workloads with higher volume or SLA requirements, paid plans provide predictable per-conversion pricing without per-file fees.

Is MCP better than direct API integration for file conversion? MCP excels when AI agents need to discover and use tools dynamically. For fixed integrations where you control the code, direct API calls are simpler. MCP adds value when the same agent might convert files, query databases, and search the web in a single session.

---

Conclusion

File conversion does not need to be the friction point in your AI-assisted workflow. An MCP server wrapping a managed FFmpeg API gives Claude Code the ability to manipulate any file format your users throw at it—without installing binaries, debugging codecs, or provisioning servers. The setup takes fifteen minutes. The time saved compounds with every conversion your agent handles automatically.

If you are building with n8n, explore our ready-made file conversion templates. For pure API access, start with a free ConvertFleet account. And if you want the fastest path to agent-powered file conversion, grab the MCP config in the download below and paste it into Claude Code today.