Automate File Conversion: Build a Claude MCP Server in 20 Minutes (2026)

TL;DR: - Build a Model Context Protocol (MCP) server that lets Claude convert files on demand using any file conversion API - MCP is Anthropic's open standard for giving AI agents persistent, tool-based capabilities beyond their training data - The complete server config and tool definitions are available as a free download below — import and run in minutes - Works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client

You need a video converted to MP4, a PDF turned into Word, or a batch of images resized — but you don't want to leave your Claude session to do it. The fix: automate file conversion by wrapping a conversion API as an MCP tool. This guide shows you exactly how, with working code you can deploy today.

If you're building with Claude Code, shipping AI agents, or just tired of manually uploading files to conversion sites, this is for you. No prior MCP experience required.

---

What Is MCP and Why Use It for File Conversion?

Model Context Protocol (MCP) is an open standard from Anthropic that lets AI assistants connect to external tools, data sources, and APIs. Think of it as a universal plug-in system: you define what a tool does, and any MCP-compatible client (Claude, Cursor, and others) can call it.

For file conversion, MCP solves a real gap. Claude knows about FFmpeg and file formats, but it can't run commands on your machine or call APIs directly. An MCP server bridges that — giving Claude the ability to actually convert files during a conversation.

Why this matters now: MCP adoption accelerated in early 2025 as Claude Code and Cursor integrated native MCP support. According to Anthropic's March 2025 announcement, MCP servers let developers "extend Claude's capabilities without modifying the core model" — making it the preferred pattern for tool-building over older function-calling approaches.

---

MCP vs. Direct API Calls: Which Approach Fits Your Workflow?

Before building, you need to decide: call a file conversion API directly from your app, or route it through MCP?

The honest trade-off: Direct API calls are faster and simpler if you don't need Claude involved. MCP adds a layer but unlocks natural-language file conversion — "resize these images to 800px and convert to WebP" — without writing custom parsing logic.

If you're already using n8n workflow examples for file conversion, direct API integration probably serves you better. If you want Claude to orchestrate conversions conversationally, MCP is the right tool.

---

How to Build a File Conversion MCP Server

Here's the part most guides skip: the actual implementation. Not a toy example — a working server with error handling, progress feedback, and support for documents, images, audio, and video.

Prerequisites

• Node.js 18+ installed
• A file conversion API key (ConvertFleet's free tier works)
• Claude Desktop or Claude Code installed

Step 1: Initialize the Project

mkdir mcp-convertfleet && cd mcp-convertfleet
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}

Step 2: Define the Tool Schemas

MCP tools are self-documenting — Claude reads the schema to understand what each tool does. Here's the ConvertFleet tool definition:

// src/tools/convertFile.ts
import { z } from "zod";

export const ConvertFileSchema = z.object({
  inputUrl: z.string().url().describe("Publicly accessible URL of the file to convert"),
  outputFormat: z.string().describe("Target format, e.g., 'mp4', 'webp', 'pdf', 'docx'"),
  options: z.object({
    quality: z.number().min(1).max(100).optional().describe("Output quality, 1-100"),
    width: z.number().optional().describe("Target width for images/videos"),
    height: z.number().optional().describe("Target height for images/videos"),
    audioBitrate: z.string().optional().describe("Audio bitrate, e.g., '128k'")
  }).optional()
});

export type ConvertFileInput = z.infer<typeof ConvertFileSchema>;

Step 3: Implement the Server

// src/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { ConvertFileSchema } from "./tools/convertFile.js";

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

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "convert_file",
      description: "Convert documents, images, audio, or video to a different format using ConvertFleet's API. Supports 178+ formats including PDF, DOCX, MP4, WEBP, MP3, and more.",
      inputSchema: {
        type: "object",
        properties": {
          inputUrl: { type: "string", format: "uri", description: "Public URL of source file" },
          outputFormat: { type: "string", description: "Desired output format extension" },
          options: {
            type: "object",
            properties: {
              quality: { type: "number", minimum: 1, maximum: 100 },
              width: { type: "number" },
              height: { type: "number" },
              audioBitrate: { type: "string" }
            }
          }
        },
        required: ["inputUrl", "outputFormat"]
      }
    }
  ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "convert_file") {
    const parsed = ConvertFileSchema.safeParse(args);
    if (!parsed.success) {
      return { content: [{ type: "text", text: `Invalid input: ${parsed.error.message}` }], isError: true };
    }

    const { inputUrl, outputFormat, options } = parsed.data;

    // Call ConvertFleet API
    const response = await fetch("https://api.convertfleet.com/v1/convert", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.CONVERTFLEET_API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        input: { url: inputUrl },
        output: { format: outputFormat, ...options }
      })
    });

    if (!response.ok) {
      const error = await response.text();
      return { content: [{ type: "text", text: `Conversion failed: ${error}` }], isError: true };
    }

    const result = await response.json();

    return {
      content: [{
        type: "text",
        text: `Conversion complete. Download: ${result.downloadUrl} (expires: ${result.expiresAt})`
      }]
    };
  }

  return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("ConvertFleet MCP server running on stdio");
}

main().catch(console.error);

Step 4: Configure Claude to Use Your Server

Create claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "convertfleet": {
      "command": "node",
      "args": ["/path/to/mcp-convertfleet/dist/index.js"],
      "env": {
        "CONVERTFLEET_API_KEY": "your-api-key-here"
      }
    }
  }
}

Build and test:

npx tsc
# Restart Claude Desktop — your tool appears in the tools menu

Grab the complete, pre-built MCP server config with additional tools for batch conversion, format detection, and webhook callbacks in the free download below. It includes error handling patterns we learned from running this in production.

---

Common Mistakes When Building MCP File Conversion Tools

Mistake 1: Blocking the main thread with large files. MCP uses stdio transport by default — if your conversion waits synchronously for a 2GB video, Claude's UI freezes. Always use async patterns with progress callbacks, or return a job ID and poll for completion.

Mistake 2: Exposing API keys in client-side code. The claude_desktop_config.json runs server-side, but teams sometimes bundle keys in Electron apps. Use environment variables and a thin backend proxy for anything user-facing.

Mistake 3: Ignoring format-specific options. A PDF-to-Word conversion needs different parameters than video transcoding. Our schema uses Zod's .describe() extensively so Claude infers the right options from context — but you must test edge cases (corrupted inputs, unsupported codecs) and return clean errors.

Mistake 4: Forgetting rate limits. ConvertFleet's API handles burst traffic, but MCP servers should implement client-side queuing. The production config in our download includes a p-retry wrapper with exponential backoff.

---

How Do I Convert Files Without Losing Quality?

Use a file conversion API that supports lossless transcoding and lets you specify quality parameters explicitly. Not all conversions are equal — re-encoding a JPEG to JPEG degrades quality, while converting PNG to WebP with -lossless preserves it.

For video, this means controlling CRF (Constant Rate Factor) or specifying a target bitrate rather than accepting defaults. For audio, choose whether you need true lossless (FLAC → FLAC) or perceptually transparent (320kbps MP3). The MCP tool above exposes these through the options object — if you don't specify, you get sensible defaults, not mystery settings.

---

What Is the Best File Conversion API?

The best file conversion API depends on your volume, format needs, and whether you need self-hosted control. For most developers riding the MCP/AI-agent wave, the decision matrix looks like this:

Our stance at ConvertFleet: We built the API we wanted for our own automation — no registration friction, no quality loss, and direct n8n/HTTP integration. If you need to compare free file conversion tools tested, that guide goes deeper on trade-offs.

---

Can I Use FFmpeg for Video Conversion?

Yes, and you should for complex video pipelines — but wrapping FFmpeg in a video conversion API saves you days of parameter tuning. FFmpeg supports 100+ codecs, but the right command for "convert this iPhone HEVC to web-optimized MP4" involves -movflags faststart, -crf 23, -profile:v baseline, and half a dozen other flags.

An API like ConvertFleet runs optimized FFmpeg under the hood with sensible presets. For MCP purposes, the value is clear: Claude calls convert_file with outputFormat: "mp4", and the API handles the encoding complexity. If you later need raw FFmpeg control, pipe the same files to a self-hosted instance.

---

How Do I Automate File Conversion in n8n?

Use n8n's HTTP Request node to call a file conversion API, or import a pre-built workflow. ConvertFleet's n8n integration is documented at n8n workflow examples for file conversion, but the pattern is straightforward:

1. Trigger (webhook, schedule, or manual)
2. HTTP Request node → POST https://api.convertfleet.com/v1/convert
3. Wait node → poll for completion if async
4. Download/save node → store the result

The MCP approach differs: instead of a scheduled workflow, conversion happens on demand within a Claude conversation. Many teams use both — MCP for ad-hoc user requests, n8n for batch processing.

---

Extending Your MCP Server: Batch, Webhooks, and Format Detection

Once the basic tool works, three additions multiply its utility:

Batch conversion: Accept an array of inputUrls and use Promise.allSettled() to process in parallel. Return a summary with individual success/failure states.

Webhook callbacks: For conversions over 30 seconds, accept a webhookUrl parameter and POST the result when done. This prevents MCP timeouts.

Format detection: Add a detect_format tool that calls ffprobe or a similar service, so Claude can answer "what format is this file?" before deciding to convert.

These patterns are included in the production-ready server config referenced above.

---

Free download

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

• ⬇ N8N Workflow: automate-file-conversion-workflow-4d2dc1efc34b3b28.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

How does MCP differ from OpenAI's function calling? MCP is an open standard, not vendor-specific. A single MCP server works with Claude, Cursor, and any compatible client — no rewrite needed when switching models.

Is the ConvertFleet API actually free? The free tier includes 100 conversions per day with no credit card required. Paid tiers scale for production use — check pricing for current rates.

Can I run the MCP server on a remote machine? Yes, though Claude Desktop uses stdio locally. For remote deployment, use the SSE transport instead of stdio, or proxy through a lightweight local bridge.

What file formats work best with this setup? All 178+ formats ConvertFleet supports, but the most common MCP use cases are: PDF ↔ Office documents, image resizing/format switching (PNG/JPEG/WEBP), and video format normalization (MOV/HEVC → MP4).

Does this work with Cursor or other MCP clients? Yes — any client implementing the MCP specification can discover and use these tools. Cursor's MCP support launched in April 2025.

---

Conclusion

You now have a working MCP server that lets Claude convert files conversationally. The pattern extends: any API can become an MCP tool, turning Claude from a chatbot into an orchestration layer for your entire stack.

The honest limit: MCP adds latency and a dependency on the server being reachable. For pure automation without AI involvement, direct API calls or n8n workflows remain cleaner. But when you want natural-language control — "convert this batch to WebP, then compress the videos" — MCP is the right abstraction.

Ready to automate file conversion without building from scratch? Get a free ConvertFleet API key and grab the complete MCP server config below.