File Conversion MCP Server for Claude Code & Cursor: A Developer's Guide

TL;DR: - MCP (Model Context Protocol) lets coding agents call external tools. Wrapping a conversion API as an MCP server gives Claude Code and Cursor native file-conversion powers. - No ffmpeg, no servers, no maintenance. The agent sends files to a managed API and gets back converted output — handled in the conversation flow. - Build it in ~30 minutes. Standard MCP server structure, one REST endpoint, and a few JSON schema definitions. - Works for PDFs, Office docs, images, audio, video. One integration covers the file types that break AI agent workflows.

Your Claude Code session is humming along. The agent just wrote a dozen files, fixed a bug, and now you ask it to "convert this PDF to text so we can feed it into the next step." It pauses. Then: "I don't have a tool for that."

That dead end is expensive. You context-switch to a terminal, hunt for ffmpeg or pdftotext, discover your system version is three years old, install dependencies, fight encoding issues — twenty minutes gone for a five-second task.

There's a better path. MCP servers extend what Claude Code and Cursor can do. Build (or use) an MCP server that wraps a conversion API, and your agent converts files natively — PDF to Word, video to GIF, audio to MP3 — without leaving the chat. This guide shows exactly how, with working code you can adapt today.

---

What Is an MCP Server and Why Does It Matter for File Conversion?

An MCP server is a lightweight bridge that exposes tools to an AI agent through a standardized protocol. Anthropic's Model Context Protocol (MCP) defines how agents like Claude Code discover and call external capabilities. Instead of the agent guessing or failing, it "sees" your conversion tool in its environment and invokes it like any other function.

For file conversion, this solves a real gap. Coding agents handle text brilliantly but choke on binary files — PDFs, images, audio, video. They can't run ffmpeg or LibreOffice unless those tools are installed, configured, and exposed through the agent's limited environment. An MCP server wrapping a conversion API pushes that work to a managed service: the agent sends the file, the API converts it, the agent gets back usable data.

The payoff: your agent pipeline stays unbroken. A common pattern we've seen in n8n AI-agent workflows (and now in Claude Code sessions) is: generate content → convert format → feed to next step. Without conversion, the chain snaps. With an MCP server, it flows lots through.

---

Claude Code vs Cursor: Which Supports MCP and How?

Both Claude Code and Cursor support MCP, but differently. Claude Code (Anthropic's CLI tool) has native, first-class MCP integration — you define servers in ~/.mcp.json or project-level config, and the agent discovers tools automatically. Cursor added MCP support in 2025; it works through Cursor's agent mode with similar configuration, though server management is slightly more manual.

Who this is for: developers building with AI agents who hit file-format boundaries and want to stay in flow. If you're already using Claude Code for serious work or running Cursor's agent mode for full-stack tasks, this removes a major friction point.

---

How to Build a File Conversion MCP Server (Step-by-Step)

This server wraps the Convertfleet conversion API — a REST endpoint that handles 178+ formats via ffmpeg and other engines. You can adapt the pattern to any file conversion services with an HTTP API.

Prerequisites

• Node.js 18+
• A Convertfleet API key (sign up free)
• Claude Code or Cursor installed

Step 1: Initialize the Project

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

Step 2: Define the Tool Schemas

Create src/index.ts. MCP servers expose tools by name with JSON schemas that tell the agent what parameters to provide.

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

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

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

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "convert_file",
        description: "Convert a file from one format to another using Convertfleet API. Supports PDF, Office, images, audio, video.",
        inputSchema: {
          type: "object",
          properties: {
            fileBase64: {
              type: "string",
              description: "Base64-encoded file content"
            },
            inputFormat: {
              type: "string",
              description: "Original file extension (e.g., 'pdf', 'docx', 'mp4')"
            },
            outputFormat: {
              type: "string",
              description: "Desired output extension (e.g., 'txt', 'pdf', 'mp3')"
            },
            options: {
              type: "object",
              description: "Optional conversion parameters (quality, page range, etc.)"
            }
          },
          required: ["fileBase64", "inputFormat", "outputFormat"]
        }
      },
      {
        name: "get_supported_formats",
        description: "List all supported input/output format pairs",
        inputSchema: { type: "object", properties: {} }
      }
    ]
  };
});

Step 3: Implement the Tool Handler

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

  if (name === "convert_file") {
    const { fileBase64, inputFormat, outputFormat, options = {} } = args;

    const payload = {
      file: fileBase64,
      input_format: inputFormat,
      output_format: outputFormat,
      ...options
    };

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

    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 complete. Download: ${result.download_url}\nExpires: ${result.expires_at}\nFormat: ${result.output_format}`
      }]
    };
  }

  if (name === "get_supported_formats") {
    // Cache or fetch from API
    return {
      content: [{
        type: "text",
        text: "Supported: 178+ formats including PDF, DOCX, XLSX, PPTX, JPG, PNG, MP4, MP3, WAV, FLAC, WebM, GIF, SVG. See https://convertfleet.com/formats for full list."
      }]
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Convertfleet MCP server running on stdio");

Step 4: Configure Claude Code to Use Your Server

Add to ~/.mcp.json (global) or ./.mcp.json (project-local):

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

Restart Claude Code. Run /tools — you'll see convert_file and get_supported_formats listed.

Step 5: Use It in a Session

User: Convert this PDF to Markdown so I can edit it.

[Claude reads the file, base64-encodes it, calls convert_file with
inputFormat="pdf", outputFormat="md"]

Claude: Done. The converted Markdown is ready at the download link.
I've also saved the text content to `document.md` for editing.

The agent never leaves the conversation. No terminal, no ffmpeg flags, no format guessing.

---

Common Mistakes When Building MCP Conversion Tools

Oversized file payloads crash the context window. Base64 inflates file size by ~33%. For files over 5 MB, upload to temporary storage first and pass a URL reference instead of raw base64. Convertfleet supports presigned URLs for this pattern.

Missing error handling for async conversions. Video transcoding takes time. If your API returns 202 Accepted with a job ID, the MCP tool needs to poll or webhook — returning immediately with "processing" confuses the agent. Return a clear status or block with a timeout.

Vague schemas confuse the agent. "Convert this file" is worse than "convert_file with explicit input_format and output_format." The agent can't see file headers reliably; it needs you to declare formats.

Forgetting to clean up temporary files. MCP servers run persistently. Stream large responses, delete temp files after upload, and set aggressive timeouts to prevent memory leaks during long sessions.

---

How Does This Compare to Running ffmpeg Locally?

Local ffmpeg wins for: sensitive data that can't leave your network, bulk batch jobs where API costs accumulate, or custom filter chains. The MCP + API pattern wins for: agent workflows where setup friction kills productivity, diverse format needs, and teams who'd rather ship than maintain infrastructure.

For most Claude Code and Cursor users, the managed path is the pragmatic choice. The time saved on a single libavcodec debugging session pays for months of API use.

---

What Is the Best File Conversion Tool for AI Agent Workflows?

The best tool is one your agent can call without leaving context. That means either native MCP support or a simple REST API wrapped cleanly.

Standalone ffmpeg tools remain unmatched for power and flexibility — but they're built for pipelines, not conversations. Tools like Pandoc, ImageMagick, and LibreOffice headless mode fill gaps but multiply complexity. For AI agents specifically, the evaluation criteria shift:

Convertfleet ranks well on these for agent use — it's built with n8n and automation-first patterns, returns structured JSON, and offers a free tier for experimentation. Other file conversion services like CloudConvert and Zamzar have APIs but weren't designed with agent workflows in mind; their pricing and response shapes assume human-initiated jobs.

---

How Do I Automate File Conversion in n8n?

Use the HTTP Request node to call a conversion API, or grab a pre-built workflow. The pattern is: trigger (webhook, schedule, or manual) → fetch file → HTTP POST to API → handle response → route to next step.

A typical n8n workflow for PDF-to-text extraction: 1. Webhook trigger receives file upload 2. HTTP Request POSTs to https://api.convertfleet.com/v1/convert with input_format: pdf, output_format: txt 3. Wait node polls for completion (or use webhook callback) 4. Code node parses result and passes text to OpenAI/Anthropic for summarization 5. Slack/Email node delivers output

The free downloadable resource for this article includes an importable n8n workflow JSON that implements this exact pattern — grab it to skip the setup.

---

Free download

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

• ⬇ N8N Workflow: conversion-api-workflow-7268e89cec33fcb9.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 the best file conversion tool?
For developers building with AI agents, an API-first service with MCP support beats local tools. It removes setup burden, handles 178+ formats, and keeps agents in flow. Local ffmpeg tools still win for custom filters and air-gapped environments.

How do I automate file conversion in n8n?
Use the HTTP Request node to POST files to a conversion API endpoint, poll or webhook for completion, then route the output. Pre-built workflows for Convertfleet's conversion API are available — import and customize with your API key.

What is the difference between ffmpeg and other conversion tools?
ffmpeg is a command-line engine for audio/video — powerful but narrow. Other tools handle PDFs (Pandoc, LibreOffice), images (ImageMagick), or Office docs separately. A conversion API wraps multiple engines behind one endpoint, handling the full spectrum without local installation.

How much does file conversion cost?
Free tiers exist for light use (typically 100–500 conversions/month). Paid plans run roughly $10–$50/month for moderate volume, or pay-per-conversion at $0.001–$0.05 per file depending on size and format. Check current pricing on any vendor's page — rates shift with volume commitments. Convertfleet offers a free tier with no registration required for basic use.

Can I use this MCP server with other APIs?
Yes — the pattern is generic. Replace the fetch() call and response parsing with any file conversion services that accept base64 or URL inputs and return download links. Adjust the tool schema descriptions so the agent knows the capabilities.

---

Conclusion

Building an MCP server for file conversion removes a persistent blocker in AI agent workflows. Instead of context-switching to terminals, debugging ffmpeg installs, or discovering your Docker image lacks fonts for PDF rendering, your agent simply calls a tool and continues.

The code above is complete and runnable. Adapt it to your API of choice, or start with Convertfleet's free tier to test the pattern. For n8n users, the companion workflow in the free download wires the same capability into no-code automation.

Start converting with Convertfleet's free API →