Metadata-Version: 2.4
Name: convertfilefast-mcp
Version: 0.1.1
Summary: MCP server for ConvertFileFast — convert 50+ file formats and run PDF/image operations as AI-agent tools.
Author: ConvertFileFast
License: MIT
Keywords: mcp,model-context-protocol,pdf,file-conversion,convert,agents
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=3.0
Requires-Dist: httpx>=0.27

# ConvertFileFast MCP server

An [MCP](https://modelcontextprotocol.io) 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 (recommended — live on PyPI)

The portable, machine-independent way — works on any machine with
[uv](https://docs.astral.sh/uv/) installed:

```json
{
  "mcpServers": {
    "convertfilefast": {
      "command": "uvx",
      "args": ["convertfilefast-mcp"],
      "env": { "CONVERTFILEFAST_API_KEY": "cff_REPLACE_WITH_YOUR_KEY" }
    }
  }
}
```

Add that block to Claude Desktop (`%APPDATA%\Claude\claude_desktop_config.json`),
Cursor (`~/.cursor/mcp.json`), or any MCP client, restart it, and ask:
*"Convert https://example.com/report.docx to PDF."*
Package page: <https://pypi.org/project/convertfilefast-mcp/>

## Local development install

To run from a local checkout (while developing the package), point your MCP
client at the repo's virtual environment instead.

### Claude Desktop

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

```json
{
  "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

```bash
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/`).

## Development

```bash
# 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:

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

---

mcp-name: io.github.MLTCorp/convertfilefast
