Setting up Convertly MCP

This guide walks through installing and configuring Convertly MCP on your machine. By the end, you’ll be able to ask an AI agent to organize files, convert images, compress video, and manage your Convertly cloud storage — all from natural language.

Local (stdio) mode is what most developers want — it gives the agent access to approved folders on your machine while running Convertly tools in the same session.

What you need

A Convertly account with an API key (get one here)
Node.js 18+ installed on your machine
An MCP-compatible client (Claude Desktop, Cursor, Cline, or similar)

Choose your mode

Convertly MCP runs in two modes. Most users want Local (stdio) mode.

Mode	Filesystem access	Use case
Local (stdio)	✅ Full access to approved folders	Claude Desktop, Cursor, Cline, Windsurf
Remote (HTTP/SSE)	❌ None	Web clients, remote servers

Install

No global installation needed. The server runs on-demand via npx:

npx -y @convertly-sh/mcp

Configure your client

Claude Desktop

macOS

Open Claude Desktop
Profile menu → Settings → Developer
Click Edit Config
Add the Convertly server to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "convertly": {
      "command": "npx",
      "args": ["-y", "@convertly-sh/mcp"],
      "env": {
        "CONVERTLY_API_KEY": "<paste-your-key-here>",
        "CONVERTLY_MCP_ROOTS": "/Users/you/Downloads:/Users/you/Pictures"
      }
    }
  }
}

Do not commit .cursor/mcp.json, Claude Desktop config, or other MCP files that contain real API keys.

Fully quit and restart Claude Desktop
Look for the Convertly server in Settings → Developer

Windows

Open Claude Desktop
Profile menu → Settings → Developer
Click Edit Config
Add the same JSON config to the file that opens
Fully quit and restart Claude Desktop

Cursor

Cursor supports the same config format and hot-reloads changes. Global config:

Open Cursor → Settings → Cursor Settings → MCP
Click Add new MCP server
Paste the JSON config into ~/.cursor/mcp.json

Project config: Create .cursor/mcp.json in your project root with the same JSON.

Cline (VS Code)

Open VS Code with Cline installed
Click the MCP Servers icon (plug) in the Cline sidebar
Click Install MCP Server
Add the config to:
- 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

Environment variables

Variable	Required	Description
`CONVERTLY_API_KEY`	For API tools	Your Convertly API key. Required for conversion, compression, media tools, cloud storage, jobs, and CDN URL helpers.
`CONVERTLY_MCP_ROOTS`	Recommended	Approved folders. `;` on Windows, `:` on macOS/Linux. See MCP agents — paths.
`CONVERTLY_BASE_URL`	No	Override the Convertly API origin. Defaults to `https://convertly.sh`.

Paths on your machine

CONVERTLY_MCP_ROOTS is an allow-list. The agent can only touch files under those folders. Windows — separate roots with ;. In JSON, prefer forward slashes:

"CONVERTLY_MCP_ROOTS": "C:/Users/you/Downloads;C:/Users/you/Projects"

Backslashes must be doubled (C:\\Users\\you\\Downloads). Single backslashes break JSON parsing. macOS / Linux — separate roots with ::

"CONVERTLY_MCP_ROOTS": "/Users/you/Downloads:/Users/you/Pictures"

~/Downloads expands to your home folder on all platforms. After changing roots, restart your MCP client. Use the list_roots tool to verify. Full reference: MCP for AI agents — paths.

First workflow

Once connected, try this prompt in your client:

Scan my Downloads folder, show me a plan to organize files by type, then move them into folders. Do not move anything until I confirm.

The agent will:

Call scan_folder to see what’s in Downloads
Call plan_organize_folder to show a dry-run organization plan
Wait for your confirmation
Call move_files with confirm=true to execute

Cloud storage workflows

You can also manage files in Convertly cloud storage:

List my Convertly cloud files, find the largest video, and get a download link for it.

The agent will:

Call list_cloud_files to browse storage
Call download_cloud_file to get a signed download URL

Image CDN URL workflows

When you need transform URLs for docs, components, or marketing pages, ask the agent to build CDN URLs instead of hand-assembling query strings:

Build a Convertly CDN URL for hero.jpg at 1200px wide with format=auto. My CDN endpoint namespace is marketing and the origin slug is site.

The agent can call build_cdn_url (from @convertly-sh/mcp) to produce URLs like:

https://cdn.convertly.sh/marketing/o/site/hero.jpg?w=1200&format=auto&q=auto

For framework projects, point it at Image CDN setup and @convertly-sh/image so <ConvertlyImage> or a Next.js loader handles srcset automatically.

Troubleshooting

”No servers added” in Developer settings

Double-check your config file syntax. The JSON must be valid and the mcpServers key must be at the root level. Restart your client after editing.

Filesystem tools return “not in approved roots”

Add the parent folder to CONVERTLY_MCP_ROOTS, use ; on Windows / : on macOS/Linux, restart the client, and call list_roots. See paths.

Windows: MCP config won’t parse

Use C:/Users/... or escaped C:\\Users\\... — not single backslashes in JSON.

HTTP mode: “Filesystem tools are unavailable”

HTTP/SSE mode cannot access your local computer. Use stdio (local) mode if you need filesystem tools.

Build Flows

Image CDN

AI Agents

What you need

Choose your mode

Install

Configure your client

Claude Desktop

Cursor

Cline (VS Code)

Environment variables

Paths on your machine

First workflow

Cloud storage workflows

Image CDN URL workflows

Troubleshooting

”No servers added” in Developer settings

Filesystem tools return “not in approved roots”

Windows: MCP config won’t parse

HTTP mode: “Filesystem tools are unavailable”

​What you need

​Choose your mode

​Install

​Configure your client

​Claude Desktop

​Cursor

​Cline (VS Code)

​Environment variables

​Paths on your machine

​First workflow

​Cloud storage workflows

​Image CDN URL workflows

​Troubleshooting

​”No servers added” in Developer settings

​Filesystem tools return “not in approved roots”

​Windows: MCP config won’t parse

​HTTP mode: “Filesystem tools are unavailable”

What you need

Choose your mode

Install

Configure your client

Claude Desktop

Cursor

Cline (VS Code)

Environment variables

Paths on your machine

First workflow

Cloud storage workflows

Image CDN URL workflows

Troubleshooting

”No servers added” in Developer settings

Filesystem tools return “not in approved roots”

Windows: MCP config won’t parse

HTTP mode: “Filesystem tools are unavailable”