> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP for AI agents
> Connect Convertly to Claude, Cursor, Cline, and other MCP clients. Run local file workflows, media conversion, compression, and docs-aware automation from natural language.
Convertly MCP is a Model Context Protocol server that lets AI agents work with files on your computer and call Convertly's media APIs from the same conversation. Organize downloads, archive old files, convert images, compress video, remove backgrounds, generate thumbnails, and look up Convertly documentation before running a workflow.
The MCP server only exposes folders you explicitly approve. API keys stay on your machine — they are not sent to the AI model.
Your MCP client starts the Convertly MCP server locally. The AI model does not receive unrestricted filesystem access — only the folders you approve are exposed through MCP tools.
For a product overview and visual walkthrough, see the [MCP & AI agents page](https://convertly.sh/mcp-ai-agents).
## How it works
Convertly MCP runs in two modes. Choose the one that matches your client and security needs.
| Mode | Transport | Filesystem access | Best for |
| ---------- | --------- | --------------------------------- | ------------------------------------------ |
| **Local** | stdio | ✅ Full access to approved folders | Claude Desktop, Cursor, Cline, Windsurf |
| **Remote** | HTTP/SSE | ❌ None | Web-based clients, remote servers, Lovable |
### Local mode (stdio) — recommended
Your MCP client launches the Convertly server as a local process. The server can read and write any folder you list in `CONVERTLY_MCP_ROOTS`. All filesystem paths are resolved and sandboxed to those roots.
### Remote mode (HTTP/SSE)
You start the server manually as an HTTP service. AI agents can use all API-based tools (conversion, compression, docs, cloud storage, jobs) but cannot access your local filesystem. Filesystem tools return an error in this mode.
```bash theme={"system"}
export CONVERTLY_API_KEY=""
CONVERTLY_MCP_HTTP_PORT=3000 npx @convertly-sh/mcp
```
Connect to `http://localhost:3000/mcp`.
**HTTP configuration:**
* `CONVERTLY_MCP_HTTP_PORT` — port to listen on
* `CONVERTLY_MCP_MAX_SESSIONS` — max concurrent SSE sessions (default: 100)
* `CONVERTLY_MCP_SESSION_TIMEOUT_MS` — idle session timeout in ms (default: 600000 = 10 min)
* `GET /health` — health check endpoint
## Client setup
### Claude Desktop
Claude Desktop was the first mainstream MCP client and has the largest ecosystem.
**macOS**
1. Open Claude Desktop
2. Click your profile menu → **Settings** → **Developer**
3. Click **Edit Config**
4. Paste the configuration into `~/Library/Application Support/Claude/claude_desktop_config.json`
5. Fully quit and restart Claude Desktop
**Windows**
1. Open Claude Desktop
2. Click your profile menu → **Settings** → **Developer**
3. Click **Edit Config**
4. Paste the JSON below into the file that opens
5. Fully quit and restart Claude Desktop
**Config structure:**
```json theme={"system"}
{
"mcpServers": {
"convertly": {
"command": "npx",
"args": ["-y", "@convertly-sh/mcp"],
"env": {
"CONVERTLY_API_KEY": "",
"CONVERTLY_MCP_ROOTS": "/Users/you/Downloads:/Users/you/Pictures"
}
}
}
}
```
Paste your dashboard API key into `CONVERTLY_API_KEY` locally. Do not commit MCP config files that contain real keys.
On Windows, use `;` to separate roots and **forward slashes** inside each path (recommended — avoids JSON escaping):
```json theme={"system"}
"CONVERTLY_MCP_ROOTS": "C:/Users/you/Downloads;C:/Users/you/Pictures"
```
If you use backslashes, each one must be escaped as `\\` in JSON:
```json theme={"system"}
"CONVERTLY_MCP_ROOTS": "C:\\Users\\you\\Downloads;C:\\Users\\you\\Pictures"
```
Unescaped backslashes (`C:\Users\...`) produce **invalid JSON** and the MCP server may not start.
## Paths and approved folders
Convertly MCP only reads and writes paths that fall under folders listed in `CONVERTLY_MCP_ROOTS`. Everything else — `scan_folder`, `convert_media`, `forma_ai_transform` with `filePath`, `outputPath`, and so on — must stay inside those roots.
### Root list (`CONVERTLY_MCP_ROOTS`)
| OS | Separator between roots | Example |
| ----------------- | ----------------------- | ---------------------------------------------- |
| **Windows** | `;` (semicolon) | `C:/Users/you/Downloads;C:/Users/you/Projects` |
| **macOS / Linux** | `:` (colon) | `/Users/you/Downloads:/Users/you/Pictures` |
* **`~`** at the start of a path expands to your home directory (`~/Downloads` → `/Users/you/Downloads` or `C:\Users\you\Downloads`).
* If `CONVERTLY_MCP_ROOTS` is omitted, only the MCP server's **current working directory** is approved (usually wherever your client launched the process).
### Windows paths in JSON config
JSON strings treat `\` as an escape character. Prefer **forward slashes** — Node.js accepts them on Windows:
```json theme={"system"}
{
"env": {
"CONVERTLY_MCP_ROOTS": "C:/Users/you/Downloads;D:/Projects/site-assets"
}
}
```
Backslashes are fine when doubled:
```json theme={"system"}
"CONVERTLY_MCP_ROOTS": "C:\\Users\\you\\Downloads;D:\\Projects\\site-assets"
```
Avoid single backslashes:
```json theme={"system"}
"CONVERTLY_MCP_ROOTS": "C:\Users\you\Downloads"
```
That is invalid JSON (`\U`, `\D`, etc. are not valid escapes) and clients may fail to parse the config.
Paths with **spaces** do not need extra escaping — keep the whole value in quotes:
```json theme={"system"}
"CONVERTLY_MCP_ROOTS": "C:/Users/you/My Projects;C:/Users/you/Downloads"
```
On Windows, the drive letter (`C:`) is part of the path, not the root separator. Only **`;`** splits multiple roots.
### macOS and Linux paths
Use normal absolute paths. Separate multiple roots with **`:`**:
```json theme={"system"}
"CONVERTLY_MCP_ROOTS": "/Users/you/Downloads:/Users/you/Pictures"
```
Spaces are fine inside quoted JSON strings:
```json theme={"system"}
"CONVERTLY_MCP_ROOTS": "/Users/you/My Projects:/Users/you/Downloads"
```
Avoid **`:`** inside a single path when you list multiple roots (uncommon on macOS/Linux). If you need a unusual path that contains `:`, approve a parent folder instead.
Tilde works the same as on Windows:
```json theme={"system"}
"CONVERTLY_MCP_ROOTS": "~/Downloads:~/Pictures"
```
### Paths in tool calls
When the agent passes `folder`, `filePath`, `outputFolder`, or `outputPath` to a tool:
* Use an **absolute** path under an approved root, or a **relative** path resolved from the server working directory.
* On Windows, forward slashes (`C:/Users/you/file.png`) are safest in prompts and tool args; backslashes usually work but agents sometimes emit invalid escapes.
* If a tool returns *outside approved roots*, add the parent directory to `CONVERTLY_MCP_ROOTS` and **restart** the MCP server (or reload the client) so the new env var is picked up.
Call `list_roots` to see the resolved allow-list the server is actually using.
### Cursor
Cursor supports the same `mcpServers` format as Claude Desktop and hot-reloads config changes.
**Global (all projects):**
1. Open Cursor
2. **Settings** → **Cursor Settings** → **MCP**
3. Click **Add new MCP server**
4. Paste the same JSON config into `~/.cursor/mcp.json`
**Project-scoped:**
Create `.cursor/mcp.json` inside your project root:
```json theme={"system"}
{
"mcpServers": {
"convertly": {
"command": "npx",
"args": ["-y", "@convertly-sh/mcp"],
"env": {
"CONVERTLY_API_KEY": "",
"CONVERTLY_MCP_ROOTS": "/Users/you/Downloads:/Users/you/Pictures"
}
}
}
}
```
### Cline (VS Code extension)
1. Open VS Code with Cline installed
2. Click the **MCP Servers** icon (plug) in the Cline sidebar
3. Click **Install MCP Server**
4. Paste the config or use the path:
* **macOS/Linux:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
* **Windows:** `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
### Lovable and other web clients
Web-based clients cannot run stdio servers. Use HTTP/SSE mode instead:
```bash theme={"system"}
export CONVERTLY_API_KEY=""
CONVERTLY_MCP_HTTP_PORT=3000 npx @convertly-sh/mcp
```
Paste `http://localhost:3000/mcp` into the client's remote MCP server field.
## Environment variables
| Variable | Required | Description |
| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `CONVERTLY_API_KEY` | For API tools | Your Convertly API key. Required for conversion, compression, media tools, cloud storage, and jobs. |
| `CONVERTLY_MCP_ROOTS` | Recommended | Approved folders. **`;`** between roots on Windows, **`:`** on macOS/Linux. See [Paths and approved folders](#paths-and-approved-folders). If omitted, only the current working directory is approved. |
| `CONVERTLY_BASE_URL` | No | Override the Convertly API origin. Defaults to `https://convertly.sh`. |
## Tools
### Convertly docs
Research before you act. These tools let an agent read Convertly documentation before calling APIs or touching files.
| Tool | Description |
| ----------------------- | ------------------------------------------------------------- |
| `list_convertly_docs` | Lists available Convertly documentation pages. |
| `search_convertly_docs` | Searches Convertly docs by topic, API name, or workflow. |
| `get_convertly_doc` | Fetches a docs page by slug or URL and returns readable text. |
### Local filesystem
These tools only work in **Local (stdio) mode**. They require paths inside `CONVERTLY_MCP_ROOTS`.
| Tool | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `list_roots` | Shows the approved folders the server can access. |
| `scan_folder` | Lists files with size, modified date, and media category. |
| `plan_organize_folder` | Creates a dry-run organization plan by file type (Images, Videos, Audio, Archives, Documents, Other). |
| `move_files` | Moves approved files to approved destinations. Requires `confirm: true`. |
| `rename_files` | Renames approved files. Requires `confirm: true`. |
| `copy_files` | Copies approved files to approved destinations. Requires `confirm: true`. |
| `create_folder` | Creates folders inside approved roots. |
| `read_file` | Reads text contents of approved files (UTF-8). |
| `create_archive` | Creates ZIP archives from approved files or folders. |
| `delete_files` | Deletes approved files. Requires `confirm: true`. |
### Media conversion
| Tool | Description |
| ---------------- | ----------------------------------------------------------------------- |
| `convert_media` | Converts images, video, audio, documents, and archives between formats. |
| `compress_media` | Compresses image, video, or audio files. |
### CDN URL builder
| Tool | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `build_cdn_url` | Builds Convertly CDN URLs for image transforms, video transcode/clip, poster frames, GIFs, and origin-backed assets. Use `trim: true` to crop transparent borders from logos. |
### Forma AI (all plans)
Generative and analysis tools that bill your **Forma AI unit quota** (included on Free, Starter, Pro, and Business). Use these when the agent or model cannot generate images natively.
| Tool | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `forma_ai_transform` | Generate from text (`image.generate`), edit, upscale, replace background, style transfer, outpaint, object removal. Saves to cloud storage; optional local `outputPath`. |
| `forma_ai_analyze` | Describe, alt-text, tags, or moderate an image (JSON). |
Requires `CONVERTLY_API_KEY`. Free and Starter hard-cap at the included Forma AI quota; Pro+ supports overage when enabled. See [Forma AI](/docs/ai-tools) and [Limits](/limits#forma-ai).
### AI media tools
| Tool | Description |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| `remove_background` | Background removal for images; use the configured ML backend for complex subject segmentation. |
| `transform_image` | Resize, crop, rotate, flip, and format-shift images. |
| `generate_thumbnail` | Creates thumbnails from images or videos. |
| `watermark_media` | Adds text or logo watermarks to images and videos. |
| `create_storyboard` | Generates storyboard grid images from videos. |
| `trim_media` | Trims video and audio to a start time and duration. |
| `video_to_gif` | Converts videos to animated GIFs. |
| `pdf_preview` | Converts PDF pages to image previews. |
| `poster_frame` | Extracts poster frames from videos. |
| `extract_audio` | Extracts audio tracks from videos. |
| `strip_metadata` | Removes metadata from media files. |
| `images_to_pdf` | Combines images into a single PDF. |
| `inspect_media` | Reads metadata and properties for media files. |
| `adjust_media` | Applies brightness, contrast, saturation, hue, grayscale, and other adjustments. |
### Cloud storage
| Tool | Description |
| --------------------- | ------------------------------------------------------------ |
| `list_cloud_files` | Lists files stored in Convertly cloud storage. |
| `download_cloud_file` | Gets a temporary signed download URL for a cloud file. |
| `save_cloud_file` | Downloads a cloud file directly to an approved local folder. |
| `delete_cloud_file` | Deletes a file from cloud storage. |
| `rename_cloud_file` | Renames a file in cloud storage. |
| `list_folders` | Lists folders in cloud storage. |
| `create_cloud_folder` | Creates a folder in cloud storage. |
| `rename_folder` | Renames a folder in cloud storage. |
### Async jobs
| Tool | Description |
| ----------- | -------------------------------------------------- |
| `list_jobs` | Lists recent async conversion and media-tool jobs. |
| `get_job` | Gets status and results for a specific job. |
### Utilities
| Tool | Description |
| -------------- | ---------------------------------------------------------------------------- |
| `transfer_url` | Downloads a public remote URL to an approved local folder (local mode only). |
## Example prompts
These are prompts you can paste directly into an MCP-enabled client.
**Research then compress:**
```text theme={"system"}
Search the Convertly docs for compression options, then compress the images in my Downloads folder into an optimized folder. Show me the plan first.
```
**Organize and convert:**
```text theme={"system"}
Scan my Downloads folder, group loose files by type, archive media older than 90 days, and convert JPG/PNG images to WebP. Do not delete anything unless I confirm.
```
**Batch rename with context:**
```text theme={"system"}
Scan my vacation photos folder, then rename all files to vacation-001.jpg, vacation-002.jpg, etc. in chronological order. Show me the rename plan first, then execute.
```
**Cloud + local workflow:**
```text theme={"system"}
List my Convertly cloud files, find the largest video, download it to my Downloads folder, trim the first 30 seconds, and compress it.
```
**Website images via Forma AI:**
```text theme={"system"}
Generate three 16:9 hero images for a SaaS landing page — minimal, high-converting, no text in frame. Save them to my Projects/site-assets folder and list the cloud file ids.
```
**Edit and upscale:**
```text theme={"system"}
Upscale my hero.png with Forma AI, then save the result locally to Downloads/hero-4k.png.
```
**Docs-aware conversion:**
```text theme={"system"}
Read the Convertly docs about vectorization options, then convert my logo.png to SVG with color preserved.
```
## Safety model
The AI model does not receive raw filesystem access.
* **Path sandboxing:** All paths are resolved against `CONVERTLY_MCP_ROOTS`. Requests outside approved folders are rejected.
* **Dry-run by default:** `plan_organize_folder` and `scan_folder` never modify files.
* **Explicit confirmation:** `move_files`, `rename_files`, `copy_files`, `delete_files`, `delete_cloud_file`, `rename_cloud_file`, and `rename_folder` require `confirm: true` before executing.
* **Non-destructive first:** Agents can show a plan, get your approval, and then execute.
## Troubleshooting
### Filesystem tools return "not in approved roots"
1. Add the **parent** folder to `CONVERTLY_MCP_ROOTS` (not just the file).
2. Use the correct separator: **`;`** on Windows, **`:`** on macOS/Linux.
3. On Windows, use forward slashes or escaped backslashes in JSON — see [Paths and approved folders](#paths-and-approved-folders).
4. Restart the MCP client after editing config so env vars reload.
5. Call `list_roots` to confirm what the server resolved.
### Invalid MCP config / server won't start (Windows)
Check JSON escaping. `C:\Users\...` with single backslashes is invalid JSON. Use `C:/Users/...` or `C:\\Users\\...`.
### HTTP mode: "Filesystem tools are unavailable"
This is expected. HTTP/SSE mode cannot access your local computer. Use stdio (local) mode if you need filesystem tools.
