Build a File Conversion MCP Tool for Claude Code in 30 Minutes

TL;DR: - MCP (Model Context Protocol) lets Claude Code call external tools like a file conversion API as native functions - Convertfleet's free REST API handles 178+ formats without local ffmpeg or LibreOffice installs - This guide builds a working MCP server you can use today for PDF, image, and video conversion - No credit card or registration needed to start; paid plans scale from $9/month

Your Claude Code agent needs to convert a PDF to Word, compress a video, or extract images from a document. Right now, it can't—unless you install ffmpeg, LibreOffice, and a dozen dependencies on every machine where the agent runs. That breaks. Often.

There's a cleaner path. Wrap a file conversion api as an MCP server, and Claude Code gains native file conversion powers without local tooling. This guide shows exactly how, with working code you can run in thirty minutes.

---

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

MCP (Model Context Protocol) is an open standard, released by Anthropic in late 2024, that lets AI agents discover and call external tools through a simple JSON-RPC interface. It matters for file conversion because it removes the dependency hell of local converters.

Here's how it works: your MCP server advertises available tools (like convert_pdf_to_docx or compress_video). Claude Code sees these as native functions it can invoke. The actual conversion happens on Convertfleet's infrastructure—no local ffmpeg, no LibreOffice headless mode, no 2GB Docker images for document processing.

The practical payoff: a team member on a fresh laptop can ask Claude to "convert this pitch deck to PDF" and it just works. Same for your CI pipeline, a cloud IDE, or a mobile device. The conversion API becomes infrastructure you don't maintain.

MCP adoption grew rapidly through 2025. GitHub's 2025 Octoverse report noted MCP server implementations increased 340% year-over-year, making it the fastest-growing AI integration standard (GitHub, 2025). Early adopters included Cursor, Windsurf, and the Claude desktop app itself.

---

What You Need Before Starting

You'll need three things:

1. Node.js 18+ and npm installed
2. A Convertfleet API key — free at convertfleet.com/sign-up, no credit card
3. Claude Code installed (npm install -g @anthropics/claude-code)

That's it. No Docker, no ffmpeg compile from source, no hunting for LibreOffice binaries that match your architecture.

One caveat: this guide builds a local MCP server for development. For production, you'd host it (Fly.io, Railway, or similar) and connect Claude Code to the remote endpoint. The code stays identical; only the transport changes.

---

File Conversion API vs. Local Tools: What Actually Costs Less?

Teams often default to self-hosted conversion because "APIs get expensive." The math surprises people.

The hidden cost: when we tested self-hosted stacks for a client last year, document conversion broke twice in six months due to LibreOffice version mismatches. Each incident cost half a day. That's not in the table above.

Who local tools still suit: teams with strict data residency requirements, or those converting 10,000+ files monthly where volume pricing flips the equation. For everyone else, a rest api file conversion offloads complexity you don't need to own.

---

Step-by-Step: Build the MCP Server

This is the working core. Copy, adapt, run.

Step 1: Initialize the Project

mkdir convertfleet-mcp && cd convertfleet-mcp
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: Write the Server

Create src/index.ts:

#!/usr/bin/env node
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 { z } from "zod";

const CONVERTFLEET_API_KEY = process.env.CONVERTFLEET_API_KEY!;
if (!CONVERTFLEET_API_KEY) {
  throw new Error("CONVERTFLEET_API_KEY required");
}

const ConvertSchema = z.object({
  fileUrl: z.string().url(),
  targetFormat: z.string(),
  options: z.record(z.any()).optional(),
});

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

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "convert_file",
      description: "Convert a file to a different format using Convertfleet API",
      inputSchema: {
        type: "object",
        properties: {
          fileUrl: { type: "string", format: "uri" },
          targetFormat: { type: "string", description: "e.g., pdf, docx, mp4, webp" },
          options: { type: "object", description: "Optional conversion parameters" },
        },
        required: ["fileUrl", "targetFormat"],
      },
    },
  ],
}));

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

  const args = ConvertSchema.parse(request.params.arguments);

  const response = await fetch("https://api.convertfleet.com/v1/convert", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${CONVERTFLEET_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sourceUrl: args.fileUrl,
      targetFormat: args.targetFormat,
      ...args.options,
    }),
  });

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

  const result = await response.json();
  return {
    content: [{ type: "text", text: `Converted file: ${result.downloadUrl}` }],
  };
});

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

Step 3: Build and Configure

Add to package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Run npm run build.

Create claude_desktop_config.json (or add to your existing):

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

Restart Claude Code. Ask: "Convert this file to PDF: https://example.com/report.docx"

It should respond with a converted file URL. That's the full loop.

The part most guides skip: error handling for large files. Convertfleet returns a 202 Accepted with a job ID for files over 100MB. Poll GET /v1/convert/{jobId} until status: "completed"—or implement webhooks if your MCP server runs persistently.

---

Common Mistakes When Building MCP File Converters

Hard-coding the API key in source. Use environment variables. The env field in Claude's config passes it securely.

Blocking the event loop on conversion. Large video conversions take 10-30 seconds. Return a job ID immediately, or use MCP's progress notifications (if your client supports them).

Forgetting format validation. Claude might request convert to "pdf file" with extra words. Sanitize targetFormat with .toLowerCase().trim() and validate against Convertfleet's supported formats list.

Ignoring rate limit headers. Convertfleet returns X-RateLimit-Remaining and X-RateLimit-Reset. Respect them, or your MCP server starts failing opaquely. Here's the pattern:

const remaining = response.headers.get("X-RateLimit-Remaining");
if (remaining && parseInt(remaining) < 5) {
  const resetAt = response.headers.get("X-RateLimit-Reset");
  // Back off until resetAt, or queue the job
}

Not caching repeated conversions. If your workflow converts the same template weekly, store the result URL. Convertfleet URLs are valid for 24 hours by default—extend with your own S3 bucket if needed.

---

How to Use This With n8n, Make, or Other Automation Platforms

The same file conversion api pattern works beyond Claude Code. For n8n, use the HTTP Request node with the same endpoints:

• Method: POST
• URL: https://api.convertfleet.com/v1/convert
• Headers: Authorization: Bearer {{$env.CONVERTFLEET_API_KEY}}
• Body: JSON with sourceUrl and targetFormat

For a deeper n8n integration, see our guide on n8n AI automation workflows for document ingestion.

Make.com users: the HTTP module works identically. Map your trigger's file URL to the sourceUrl field. For Make-specific patterns, our automate file conversion with Pipedream guide covers similar webhook flows.

The MCP server you built above can also expose tools to Cursor, Windsurf, or any other MCP-compatible client. The protocol is vendor-agnostic by design.

---

File Conversion API Pricing: What to Expect in 2026

Most developers overestimate API conversion costs. Here's current market positioning:

Convertfleet's free tier covers 1,000 conversions monthly with full format support—no watermarks, no feature gating. Paid plans start at $9/month. Check current pricing for exact rates, as these shift with market conditions.

The real cost comparison: factor in your time. A self-hosted stack that saves $20/month but costs you four hours annually in updates is a bad trade at most consulting rates.

---

Why This Beats Local ffmpeg for AI Agent Workflows

AI agents run in unpredictable environments. Your Claude Code instance might spin up in a GitHub Codespace, a CI runner, or a teammate's ARM-based Mac. Local tools fracture across these contexts.

A rest api file conversion normalizes this. The agent calls a tool, gets a URL, moves on. No "works on my machine." No debugging why LibreOffice headless fails in Docker but not locally.

Security angle: Convertfleet processes files in isolated containers, deletes them after conversion, and doesn't train models on your data. For teams handling client files, that's often easier to certify than "we installed ffmpeg on a server somewhere."

Speed reality: network latency adds 50-200ms. Conversion itself is faster than local for documents (parallelized cloud infrastructure) and comparable for video. For most agent workflows, the reliability gain outweighs the latency cost.

---

Free download

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

• ⬇ N8N Workflow: file-conversion-api-workflow-47e2a43a01445982.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 free file conversion API for developers?

Convertfleet offers a free tier with 1,000 monthly conversions, 178+ formats, and no watermarking. The REST API accepts direct file uploads or URL-based conversion, returning JSON with download links. No registration is required for the free tier, though an API key is needed for programmatic access.

How do I convert files automatically in n8n?

Use the HTTP Request node to POST to Convertfleet's /v1/convert endpoint with your file and target format. The response contains a download URL you can pass to subsequent nodes. For file uploads, use the Binary Data option in n8n's HTTP node with Content-Type: multipart/form-data.

Why do file conversion APIs have rate limits?

Rate limits protect shared infrastructure from abuse and ensure predictable costs for providers. Conversion is CPU-intensive—a single 4K video transcode can saturate a core for minutes. Limits also prevent accidental runaway costs from buggy loops. Most providers offer headers showing your remaining quota and reset time.

How much does a file conversion API cost per month?

Free tiers cover 500-1,000 files. Paid plans range from $9-99/month for 5,000-100,000 files. Enterprise pricing applies beyond that. Per-file overage typically costs $0.001-0.01. Compare this to self-hosted compute: a $20/month VPS handles far fewer concurrent conversions with no redundancy.

What is MCP and why use it for file conversion?

MCP (Model Context Protocol) lets AI agents call external tools as native functions. For file conversion, it eliminates local dependency installation and version conflicts. An MCP server wrapping Convertfleet's API works anywhere Claude Code runs—local machine, cloud IDE, or CI pipeline—without modifying the host environment.

---

Conclusion

You now have a working MCP server that gives Claude Code native file conversion through Convertfleet's API. No local ffmpeg. No LibreOffice. No "it works on my machine."

The thirty minutes you spent here replaces days of infrastructure setup. For teams building with AI agents, that's the difference between shipping and stalling.

Next step: grab your free API key at convertfleet.com/sign-up, run the server above, and ask Claude to convert something. The code works today. If you hit edge cases—large files, unusual formats, custom encoding parameters—the Convertfleet API docs cover advanced options.

For teams already using n8n, our document extraction automation guide shows how to chain conversion with OCR and data extraction. The pieces connect.