MCP Server Guide

ConvX includes a built-in MCP server so AI agents like Claude, Cursor, and VS Code can convert files as naturally as they write code.

Quick setup

Start the MCP server:

convx mcp

Configuration

Add ConvX to your AI agent's MCP configuration:

{
  "mcpServers": {
    "convx": {
      "command": "convx",
      "args": ["mcp"]
    }
  }
}

Claude Desktop

Add the above config to your Claude Desktop settings under MCP Servers. Restart Claude after adding it.

Cursor

Add the ConvX MCP server in Cursor's settings panel under the MCP section.

VS Code

Use an MCP-compatible VS Code extension and add ConvX to its server configuration.

Available tools

ConvX exposes 9 MCP tools. Your AI agent discovers these automatically.

convert_file

Convert a single file from one format to another.

convert_file({
  input_path: "/path/to/video.mov",
  output_format: "mp4",
  quality: 80,
  preset: "discord",
  max_size: 8388608,
  overwrite: true
})

batch_convert

Convert multiple files at once.

batch_convert({
  input_paths: ["/path/*.png"],
  output_format: "webp",
  output_directory: "/path/to/output",
  quality: 80
})

get_supported_formats

List all supported formats grouped by category. No parameters required.

get_conversion_targets

Get all formats a specific input format can convert to.

get_conversion_targets({ input_format: "mp4" })

can_convert

Check if a specific conversion path is supported.

can_convert({ from: "heic", to: "jpg" })

get_file_info

Get metadata and conversion targets for a specific file.

get_file_info({ path: "/path/to/video.mp4" })

list_presets

List all built-in presets. No parameters.

get_preset

Get details for a specific preset.

get_preset({ name: "discord" })

check_dependencies

Check which format categories are available on this system. No parameters.

Example conversations

Batch converting screenshots

You: "Convert all the PNGs in my screenshots folder to WebP"

Agent calls: batch_convert({
  input_paths: ["~/Screenshots/*.png"],
  output_format: "webp",
  quality: 80
})

Result: 23 files converted. 47MB → 12MB (74% smaller)

Format discovery

You: "What can I convert this PDF to?"

Agent calls: get_conversion_targets({ input_format: "pdf" })

Result: pdf can convert to: docx, pptx, xlsx, png, jpg

Discord-ready video

You: "Make this video small enough for Discord"

Agent calls: convert_file({
  input_path: "~/clip.mov",
  preset: "discord"
})

Result: Converted. 47.2MB → 7.8MB. Ready for Discord.

Troubleshooting

"No such file or directory"

The MCP client can't find the ConvX binary. Double-check the command path in your config. Use which convx to find the correct path.

Conversions failing

Run convx check (or use the check_dependencies MCP tool) to verify all format categories are available on your system.