convertfilefast-mcp 0.1.0

MCP server for ConvertFileFast — convert 50+ file formats and run PDF/image operations as AI-agent tools.

ConvertFileFast MCP server

An MCP server that lets AI agents (Claude Desktop, Claude Code, Cursor, etc.) convert files and run PDF/image operations through the ConvertFileFast API.

It is a separate service that talks to the ConvertFileFast REST API over HTTP — it does not import the backend, so it never affects the API's dependencies, and it mirrors how the hosted MCP runs in production.

Tools

Tool	What it does
convert_file	Convert between 40+ format pairs (DOCX→PDF, PDF→CSV, PDF→JPG, HTML→PDF, URL→PDF, PNG→JPG, CSV→JSON, …)
merge_pdfs	Merge multiple PDFs into one
split_pdf	Extract pages/ranges from a PDF
compress_pdf	Reduce PDF size (low/medium/high/maximum)
rotate_pdf	Rotate pages (90/180/270°)
protect_pdf	Add password protection
unlock_pdf	Remove password protection
resize_image	Resize an image
compress_image	Compress an image (and optionally cap dimensions)

Every tool accepts a public source_url (preferred — the agent passes a URL and never handles binary) or file_base64. The result file is written to the output directory and the tool returns its path.

Prerequisites

A ConvertFileFast API key (starts with cff_). Create one at https://www.convertfilefast.com/signup.

Configuration

The server reads these environment variables:

Variable	Default	Purpose
CONVERTFILEFAST_API_KEY	—	Your cff_ key (sent as X-API-Key)
CONVERTFILEFAST_API_BASE	https://api.convertfilefast.com	API base URL (set to http://127.0.0.1:8000 to test against a local backend)
CONVERTFILEFAST_OUTPUT_DIR	~/ConvertFileFast	Where converted files are saved
CONVERTFILEFAST_TIMEOUT	180	Per-request timeout (seconds)

Install (local, works today)

Until the package is published to PyPI, point your MCP client at the local virtual environment created for this repo.

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "convertfilefast": {
      "command": "C:\\Projetos\\GitHub-Clones\\conversor-pdf\\mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Projetos\\GitHub-Clones\\conversor-pdf\\mcp\\server.py"],
      "env": {
        "CONVERTFILEFAST_API_KEY": "cff_REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}

Restart Claude Desktop, then ask: "Convert https://example.com/report.docx to PDF."

Cursor

Add the same block to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).

Claude Code

claude mcp add convertfilefast \
  --env CONVERTFILEFAST_API_KEY=cff_REPLACE_WITH_YOUR_KEY \
  -- "C:\Projetos\GitHub-Clones\conversor-pdf\mcp\.venv\Scripts\python.exe" \
     "C:\Projetos\GitHub-Clones\conversor-pdf\mcp\server.py"

Testing against the local backend: add "CONVERTFILEFAST_API_BASE": "http://127.0.0.1:8000" to the env block and start the backend first (uvicorn app.main:app from api/).

Future: published install

Once published to PyPI, the portable, machine-independent config will be:

{
  "mcpServers": {
    "convertfilefast": {
      "command": "uvx",
      "args": ["convertfilefast-mcp"],
      "env": { "CONVERTFILEFAST_API_KEY": "cff_..." }
    }
  }
}

Development

# from this directory
uv venv .venv --python 3.12
uv pip install --python .venv/Scripts/python.exe fastmcp httpx

# run (stdio)
CONVERTFILEFAST_API_KEY=cff_... .venv/Scripts/python.exe server.py

Inspect the tools with the MCP Inspector:

npx @modelcontextprotocol/inspector .venv/Scripts/python.exe server.py