> ## 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.

# Setting up Convertly MCP

> Step-by-step guide to connecting Claude Desktop, Cursor, Cline, and other MCP clients to Convertly for local file workflows and media processing.

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.

<div className="convertly-callout">
  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.
</div>

## What you need

* A Convertly account with an API key ([get one here](https://convertly.sh/app))
* 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`:

```bash theme={"system"}
npx -y @convertly-sh/mcp
```

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

```json theme={"system"}
{
  "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.

5. Fully quit and restart Claude Desktop
6. 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

| 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](/docs/mcp-agents#paths-and-approved-folders). |
| `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:

```json theme={"system"}
"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 `:`:

```json theme={"system"}
"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](/docs/mcp-agents#paths-and-approved-folders).

## First workflow

Once connected, try this prompt in your client:

```text theme={"system"}
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:

```text theme={"system"}
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

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

```text theme={"system"}
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](/guides/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](/docs/mcp-agents#paths-and-approved-folders).

### 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.