Skip to main content

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.

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.

​
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.
ModeFilesystem accessUse case
Local (stdio)✅ Full access to approved foldersClaude Desktop, Cursor, Cline, Windsurf
Remote (HTTP/SSE)❌ NoneWeb clients, remote servers

​
Install

No global installation needed. The server runs on-demand via npx: 
npx -y @convertly/mcp
For local development, you can also run the server directly from the repo: 
node packages/convertly-mcp/dist/index.js

​
Configure your client

​
Claude Desktop

macOS
  1. Open Claude Desktop
  2. Profile menu → Settings → Developer
  3. Click Edit Config
  4. Add the Convertly server to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "convertly": {
      "command": "npx",
      "args": ["-y", "@convertly/mcp"],
      "env": {
        "CONVERTLY_API_KEY": "ctly_live_...",
        "CONVERTLY_MCP_ROOTS": "/Users/you/Downloads:/Users/you/Pictures"
      }
    }
  }
}
  1. Fully quit and restart Claude Desktop
  2. Look for the Convertly server in Settings → Developer
Windows
  1. Open Claude Desktop
  2. Profile menu → Settings → Developer
  3. Click Edit Config
  4. Add the same JSON config to the file that opens
  5. Fully quit and restart Claude Desktop

​
Cursor

Cursor supports the same config format and hot-reloads changes. Global config:
  1. Open Cursor → Settings → Cursor Settings → MCP
  2. Click Add new MCP server
  3. 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)

  1. Open VS Code with Cline installed
  2. Click the MCP Servers icon (plug) in the Cline sidebar
  3. Click Install MCP Server
  4. 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

VariableRequiredDescription
CONVERTLY_API_KEYFor API toolsYour Convertly API key. Required for conversion, compression, media tools, currency, cloud storage, and jobs.
CONVERTLY_MCP_ROOTSRecommendedApproved folders the MCP server can access. Use : on macOS/Linux, ; on Windows. If omitted, only the current working directory is approved.
CONVERTLY_BASE_URLNoOverride the Convertly API origin. Defaults to https://convertly.sh.

​
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:
  1. Call scan_folder to see what’s in Downloads
  2. Call plan_organize_folder to show a dry-run organization plan
  3. Wait for your confirmation
  4. 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:
  1. Call list_cloud_files to browse storage
  2. Call download_cloud_file to get a signed download URL

​
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 folder to CONVERTLY_MCP_ROOTS. On Windows, use ; as the separator. On macOS/Linux, use :.

​
HTTP mode: “Filesystem tools are unavailable”

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