MCP Server Documentation

Convert files directly from your AI coding assistant using the Model Context Protocol (MCP). Connect Claude Code, Cursor, Gemini CLI, or any MCP-compatible tool to access 140+ file conversions.

Quick Start

Get your first conversion running in 30 seconds. Add the MCP server to Claude Code and convert a file:

1. Add the MCP server

bash

claude mcp add --transport http conversiontools https://mcp.conversiontools.io/mcp

2. Ask Claude to convert a file

Convert report.xlsx to PDF

Claude will handle authentication on the first run (a browser window opens for you to log in) and then perform the conversion automatically.

Installation Methods

Claude Code Plugin (recommended)

The plugin includes the MCP server connection and built-in AI instructions for optimal conversion results.

bash

claude plugin marketplace add conversiontools/agent-skills
claude plugin install conversiontools

See the Claude Code Plugin docs for more details.

Claude Code (manual MCP setup)

Add the MCP server directly with a single command:

bash

claude mcp add --transport http conversiontools https://mcp.conversiontools.io/mcp

Cursor

Add to your Cursor MCP configuration:

json

{
  "mcpServers": {
    "conversiontools": {
      "url": "https://mcp.conversiontools.io/mcp"
    }
  }
}

Gemini CLI

bash

gemini extensions install https://github.com/conversiontools/gemini-extension

Other MCP-Compatible Tools

Any tool that supports the Model Context Protocol can connect to:

bash

https://mcp.conversiontools.io/mcp

Authentication

Choose the authentication method that works best for your setup:

Option A: OAuth (recommended)

Default

No configuration required. On first use, a browser window opens for you to log in to your Conversion Tools account. Your credentials are securely stored for future sessions and automatically refreshed when they expire.

Run a conversion or call auth_login
Browser opens to conversiontools.io
Log in and authorize the connection
You are authenticated -- credentials are saved locally

Option B: API Token

For CI/CD pipelines, server environments, or when browser login is not available. Get your API token from your profile page.

Set as environment variable:

bash

export CT_API_TOKEN=your_api_token_here

Or pass it in the MCP server URL:

bash

claude mcp add --transport http conversiontools https://mcp.conversiontools.io/mcp --header "Authorization: Bearer your_api_token_here"

Available Tools

The MCP server provides 8 tools for your AI assistant:

Tool	Description
`convert_file`	Convert a file from one format to another. Supports 140+ conversion types.
`request_upload_url`	Get a signed URL for uploading large files (larger than 5 MB).
`list_converters`	List available file converters. Discover what conversions are supported.
`find_converter`	Find the best converter for converting between two specific formats.
`get_converter_info`	Get detailed information about a specific converter, including supported options.
`auth_status`	Check current authentication status and account information.
`auth_login`	Login via OAuth. Opens a browser window for authentication.
`auth_logout`	Logout and clear stored credentials.

Usage Examples

Once connected, just ask your AI assistant naturally. Here are common workflows:

Convert Excel to PDF

Convert report.xlsx to PDF

Your AI assistant will use convert_file to transform the spreadsheet into a PDF document.

Convert JSON to CSV

Transform data.json into a CSV file

Works with nested JSON arrays -- the converter flattens the structure into rows and columns.

Extract text from an image (OCR)

Extract the text from receipt.jpg

Uses OCR to recognize and extract text from images and scanned documents.

Batch convert files

Convert all the PNG files in the screenshots/ folder to WebP

Your AI assistant will iterate through each file and convert them one by one.

Find available converters

What formats can I convert a PDF to?

Uses list_converters to show all available output formats for PDFs.

AI-powered data extraction

Extract the invoice data from invoice.pdf as a JSON file

AI-powered converters can extract structured data from complex documents like invoices, receipts, and reports.

Supported Formats

Convert between 140+ file formats across 13 categories:

Documents

DOCX, DOC, PPTX, PPT, XLSX, XLS, Markdown, ODS, HTML, LaTeX

Data Formats

JSON, CSV, XML, YAML, Parquet, JSONL, BSON, Excel

Images

PNG, JPG, WebP, AVIF, HEIC, JXL, SVG, BMP, TIFF, GIF

PDF Processing

PDF to Word, Excel, CSV, Text, HTML, JPG, PNG, SVG, TIFF, EPUB

Audio

MP3, WAV, FLAC

Video

MP4, MOV, MKV, AVI

E-books

EPUB, MOBI, AZW, AZW3, FB2, FBZ, PDF

OCR

PNG, JPG, PDF to Text, searchable PDF

AI Text-to-Speech

Text, DOCX, PDF, Markdown to MP3

AI Speech-to-Text

MP3, WAV, FLAC to Text

AI-Powered

PDF, Images to JSON, CSV, Excel, Markdown

Subtitles

SRT, VTT, ASS, CSV, Excel, Text

Web

URL/HTML to PDF, JPG, PNG, CSV

View full converter list for detailed information about each converter and its options.

Pricing

MCP uses the same conversion limits as your Conversion Tools account:

Free tier: 100 conversions per month (max 10 per day)
Paid plans: Higher limits and priority processing

View pricing plans or API pricing for details.

Troubleshooting

Common issues and how to resolve them:

OAuth login window does not open

Make sure your browser is set as the default system browser. If running inside a container or remote environment without a display, use the API token method instead.

Authentication expired or token invalid

Run the auth_login tool to re-authenticate, or set a fresh API token in the CT_API_TOKEN environment variable.

File too large to convert

For files larger than 5 MB, use the request_upload_url tool first to get a signed upload URL, upload the file, then pass the returned file_id to convert_file.

Conversion format not supported

Use list_converters or find_converter to check which formats are available. If you need a format that is not listed, contact us.

Conversion fails or returns an error

Check that the input file is valid and not corrupted. Some conversions have file size limits depending on your plan.

MCP server not connecting

Verify the server URL is https://mcp.conversiontools.io/mcp and that your network allows HTTPS connections.

Need Help?

Check our API Documentation for detailed information about converters and options.

Looking for the Claude Code Plugin? View plugin documentation for automatic setup with built-in conversion instructions.

Having issues? Contact us and we will help you get set up.

Ready to Get Started?

Add the MCP server to your AI assistant and start converting files without leaving your workflow.

bash

claude mcp add --transport http conversiontools https://mcp.conversiontools.io/mcp

Claude Code Plugin API Documentation