> ## Documentation Index
> Fetch the complete documentation index at: https://help.clueso.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Clueso MCP

> Use Clueso from your AI assistant using MCP

Connecting the Clueso MCP to your AI assistant lets you create videos and documents in Clueso without leaving your chat/coding environment. Your AI assistant can create in bulk, use conversation memory, run multi-tool workflows, and edit end to-end; all through natural language.

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/t4xXPfljsRU" title="Video tutorial" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen />

## Before you start

To use the Clueso MCP server, you'll need:

* An AI assistant that supports MCP servers, such as:
  * ChatGPT
  * Claude
  * Claude Code
  * Gemini CLI
  * Cursor
  * VS Code (with GitHub Copilot or a compatible MCP extension)
* A Clueso account

<Note>
  The Clueso MCP server is available on all Clueso plans. Some tools — such as video export and advanced branding - require a paid plan.
</Note>

***

## Connect your AI assistant

<Tabs>
  <Tab title="ChatGPT">
    <Info>
      This setup requires a **ChatGPT paid plan** (Plus, Pro, Team, Enterprise, or Edu). A paid ChatGPT plan is recommended for better outputs
    </Info>

    1. Open **ChatGPT** and go to **Settings**.
    2. Click **Apps**, then enable **Developer Mode**.
    3. Click **Add** (or **Create**) and enter the following URL: [https://connect.clueso.io/mcp](https://connect.clueso.io/mcp)
    4. Name it `Clueso` and save.
    5. A browser window will open — sign in to Clueso and click **Allow** to authorize.
    6. In the chat, click the **+** icon below the chatbox, hover over **More**, and select **Developer mode** to activate Clueso for that chat.

    **Test it:**

    > "Create a Clueso guide from this PPT, add a voiceover to each slide explaining the key point, and export it as a video."
  </Tab>

  <Tab title="Claude">
    <Info>
      Claude connectors require a **Claude paid plan** (Pro, Team, or Enterprise).
    </Info>

    1. Open **Claude** (web or desktop).
    2. Click your **Profile** in the top right, then go to **Settings**.
    3. Navigate to **Connectors** and click **Add custom connector**.
    4. Enter the following URL: [https://connect.clueso.io/mcp](https://connect.clueso.io/mcp)
    5. A browser window will open — sign in to Clueso and click **Allow** to authorize.

    Clueso will now appear in the tools panel for every new chat.

    **Test it:**

    > "Create a Clueso guide from this PPT, add a voiceover to each slide explaining the key point, and export it as a video."
  </Tab>

  <Tab title="Claude Code">
    Run the following command in your terminal to add the Clueso MCP server to Claude Code:

    ```bash theme={null}
    claude mcp add --transport http Clueso https://connect.clueso.io/mcp
    ```

    Claude Code will prompt you to authorize Clueso in your browser. Sign in and click **Allow**.

    <Tip>
      You can also scope the MCP server to a specific project by running the command inside that project's directory and adding the `--scope project` flag.
    </Tip>

    To verify the server was added:

    ```bash theme={null}
    claude mcp list
    ```

    You should see `Clueso` listed with a `✓ connected` status.

    **Test it** by starting a session:

    ```bash theme={null}
    claude
    ```

    > "Create a Clueso guide from this PPT, add a voiceover to each slide explaining the key point, and export it as a video."

    <Info>
      For full Claude Code MCP documentation, see [Anthropic's Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp).
    </Info>
  </Tab>

  <Tab title="Gemini CLI">
    <Warning>
      Gemini CLI MCP support requires **Gemini CLI version 0.1.7 or later**. Run `gemini --version` to check.
    </Warning>

    1. Open your terminal and navigate to your project directory.
    2. Add the Clueso MCP server to your Gemini CLI settings:

    ```bash theme={null}
    gemini mcp add clueso https://connect.clueso.io/mcp
    ```

    3. Gemini CLI will open a browser window for you to authorize Clueso. Sign in and click **Allow**.

    Alternatively, you can manually configure Gemini CLI by editing `~/.gemini/settings.json`:

    ```json ~/.gemini/settings.json theme={null}
    {
      "mcpServers": {
        "clueso": {
          "httpUrl": "https://connect.clueso.io/mcp",
          "timeout": 10000
        }
      }
    }
    ```

    **Test it:**

    ```bash theme={null}
    gemini
    ```

    > "Show me all projects in my Clueso workspace."

    <Info>
      For more on Gemini CLI, see the [Gemini CLI GitHub repo](https://github.com/google-gemini/gemini-cli).
    </Info>
  </Tab>

  <Tab title="Cursor">
    <Info>
      MCP tools in Cursor are only available in **Agent mode**. Make sure you're in an Agent chat session.
    </Info>

    <Warning>
      Requires **Node.js 22.16 or later** with npm. [Download Node.js →](https://nodejs.org/en/download)
    </Warning>

    ### Option 1 — Automatic setup (recommended)

    Click the link below to auto-configure Clueso in Cursor:

    ```text theme={null}
    cursor://anysphere.cursor-deeplink/mcp/install?name=Clueso&config=eyJjb21tYW5kIjoibnB4IC15IG1jcC1yZW1vdGVAbGF0ZXN0IGh0dHBzOi8vY29ubmVjdC5jbHVlc28uaW8vbWNwIn0=
    ```

    ### Option 2 — Manual setup

    1. Create the Cursor config directory in your project root (if it doesn't exist):

    ```bash theme={null}
    mkdir -p .cursor && touch .cursor/mcp.json
    ```

    2. Add the following to `.cursor/mcp.json`:

    ```json .cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "Clueso": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote@latest",
            "https://connect.clueso.io/mcp"
          ]
        }
      }
    }
    ```

    3. **Restart Cursor** to apply the config.
    4. A browser tab will open — sign in to Clueso and click **Allow**.

    **Test it** by opening an Agent chat:

    > "Create a new Clueso project in the Onboarding folder."

    <Info>
      For more details, see the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers).
    </Info>
  </Tab>

  <Tab title="VS Code">
    <Info>
      MCP tools in VS Code require **GitHub Copilot** (or another compatible MCP extension) and are only available in **Agent mode**.
    </Info>

    <Warning>
      Requires **Node.js 22.16 or later** with npm. [Download Node.js →](https://nodejs.org/en/download)
    </Warning>

    1. Create the VS Code config directory in your project root (if it doesn't exist):

    ```bash theme={null}
    mkdir -p .vscode && touch .vscode/mcp.json
    ```

    2. Add the following to `.vscode/mcp.json`:

    ```json .vscode/mcp.json theme={null}
    {
      "servers": {
        "Clueso": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote@latest",
            "https://connect.clueso.io/mcp"
          ]
        }
      }
    }
    ```

    3. **Restart VS Code** to apply the configuration.
    4. A browser tab will open — sign in to Clueso and click **Allow** to authorize.

    **Test it** by opening a GitHub Copilot Agent chat:

    > "List all guides in my Clueso workspace."

    <Info>
      For more details, see the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
    </Info>
  </Tab>
</Tabs>

***

## Verify the connection

After setup, confirm the Clueso MCP server is working:

1. **Look for the Clueso tool** in your AI assistant's tools or connectors panel.
2. **Run a test prompt**, for example:
   > "Show me my most recently updated Clueso project."
3. Your AI assistant should ask you to **approve a tool call**. Click **Allow** (or **Approve**) and wait for the response.

If the connection is successful, you'll see a list of your Clueso projects returned in the chat.

<Tip>
  If the connection fails or times out, try restarting your AI assistant and re-authorizing. Make sure you're signed into Clueso in your browser.
</Tip>

***

## What you can do with Clueso MCP

Once connected, you can ask your AI assistant to:

<CardGroup cols={2}>
  <Card title="Create projects" icon="plus">
    "Create a new video called 'How to reset your password'."
  </Card>

  <Card title="Add voiceovers" icon="mic">
    "Add a voiceover to the first clip of my onboarding guide."
  </Card>

  <Card title="Export videos" icon="video">
    "Export my 'Getting Started' project as a video."
  </Card>

  <Card title="Update articles" icon="pen">
    "Update the article in my 'API Docs' project with this new content."
  </Card>
</CardGroup>

***

## Tools available

Your AI assistant can call the following Clueso tools once connected. You don't need to memorize them — just describe what you want and your assistant will pick the right ones. This list is provided as a reference for what's possible.

### Find and browse

| Tool               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `find`             | Search or list anything in your workspace by type — projects, folders, clueprints, workspaces, voices, background music, sound effects, backgrounds, saved images and videos, AI image-generation styles, and saved components. Filter by name, or leave the search term off to list everything of a type. For example: `find(type='projects')`, `find(type='music', query='upbeat')`, or `find(type='voices', language='en')`. |
| `switch_workspace` | Switch the active workspace for the current session.                                                                                                                                                                                                                                                                                                                                                                            |

### Projects

| Tool                | What it does                                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `create_project`    | Create a new project.                                                                                             |
| `get_project`       | Read a project's structure — clips, durations, element counts, and audio tracks.                                  |
| `update_project`    | Rename a project, edit its description, move it between folders, or change its aspect ratio (16:9, 9:16, or 1:1). |
| `duplicate_project` | Clone an entire project into a fresh, independent copy.                                                           |
| `get_capabilities`  | Report which add-ons (recording, code grounding) are available on the account.                                    |

### Clips

| Tool             | What it does                                                                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `add_clips`      | Add clips to a project — blank slides, PowerPoint slides, or cuts from a video/audio file. Set each clip's background and entrance transition as you add it. |
| `get_clip`       | Inspect a clip and optionally return a rendered preview. Ask for only the fields you need to keep responses lean.                                            |
| `update_clips`   | Update one or many clips in a single call — backgrounds, durations, visibility, or entrance transitions.                                                     |
| `split_clip`     | Split a video clip into two at a chosen point.                                                                                                               |
| `remove_clip`    | Delete a clip from a project.                                                                                                                                |
| `duplicate_clip` | Clone a clip — within the same project, or from another project.                                                                                             |

### Elements (text, images, shapes, generated media)

| Tool                  | What it does                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| `add_elements`        | Place text, images, shapes, or animations onto a clip. Text is auto-measured so it fits its box. |
| `update_elements`     | Edit the position, size, or content of existing elements.                                        |
| `remove_elements`     | Remove one or more elements, across one or more clips, in a single call.                         |
| `reorder_elements`    | Change the z-order (front-to-back stacking) of elements inside a clip.                           |
| `remove_from_project` | Remove a single element from a clip, or a music/SFX track from a project.                        |
| `get_element_schema`  | Show the properties available for a given element type.                                          |
| `generate_media`      | Generate an AI image or canvas-code animation directly into a clip.                              |

### Voiceover and audio

| Tool              | What it does                                                               |
| ----------------- | -------------------------------------------------------------------------- |
| `voiceover_batch` | Generate AI voiceovers for one or many clips from a script.                |
| `set_voice`       | Pick the AI voice used for narration.                                      |
| `add_audio`       | Add background music or a sound effect to a project.                       |
| `update_audio`    | Adjust an existing music or SFX track — volume, fades, timing, or looping. |
| `analyze_audio`   | Get a transcript and analysis of an audio file.                            |

### Sync (for video clips with source recordings)

| Tool             | What it does                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `auto_sync`      | Detect natural sync points in a recording (UI state changes, narrated steps) and insert them automatically. |
| `add_sync_point` | Pin a specific word in the voiceover to a specific moment in the underlying recording.                      |

### Articles

| Tool                   | What it does                                                                            |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `get_article`          | Read the article tied to a project.                                                     |
| `update_article`       | Edit the article's markdown content.                                                    |
| `add_article_media`    | Add a screenshot or GIF (from the project's video or an uploaded image) to the article. |
| `update_article_media` | Edit a screenshot's zoom, crop, or annotation shapes.                                   |

### Recording

| Tool            | What it does                                       |
| --------------- | -------------------------------------------------- |
| `record_screen` | Start a new screen or browser recording in Clueso. |

### Files and assets

| Tool            | What it does                                                 |
| --------------- | ------------------------------------------------------------ |
| `upload_file`   | Upload a file (image, video, audio, PPTX) to your workspace. |
| `check_uploads` | Retrieve the files a user dropped on a hosted upload link.   |

### Clueprints (reusable templates)

| Tool               | What it does                                                                        |
| ------------------ | ----------------------------------------------------------------------------------- |
| `create_clueprint` | Save a project as a reusable clueprint.                                             |
| `get_clueprint`    | Read a clueprint's metadata, file tree, or specific files.                          |
| `update_clueprint` | Edit a clueprint's metadata, write new files, or delete existing files in one call. |

### Collaboration

| Tool          | What it does                  |
| ------------- | ----------------------------- |
| `add_comment` | Leave a comment on a project. |

### Export

| Tool                | What it does                                                              |
| ------------------- | ------------------------------------------------------------------------- |
| `estimate_duration` | Estimate voiceover duration for one or more clips from their script text. |
| `export_project`    | Render and export a project as a video.                                   |

***

## Combine tools for end-to-end workflows

The real power of Clueso MCP comes from chaining these tools together. Your AI assistant can call several tools in sequence to complete a full workflow — no manual hand-offs, no copying assets between tools. Just describe the outcome you want, and the assistant figures out which tools to call and in what order.

A few examples:

* **"Turn this slide deck into a narrated explainer video."** Uploads the PPTX (`upload_file`), creates a project (`create_project`), imports each slide as a clip (`add_clips` with `kind=pptx`), generates AI narration per slide (`voiceover_batch`), then renders the final video (`export_project`).
* **"Build a product release video from this changelog."** Creates a project (`create_project`), adds blank clips (`add_clips` with `kind=blank`), drops in headlines and AI illustrations (`add_elements`, `generate_media`), generates a voiceover from the script (`voiceover_batch`), and exports it (`export_project`).
* **"Convert this Loom recording into a polished Clueso guide."** Uploads the recording (`upload_file`), adds it as a clip (`add_clips` with `kind=video`), detects steps automatically (`auto_sync`), layers titles and zoom callouts (`add_elements`), regenerates cleaner narration (`voiceover_batch`), and exports the result (`export_project`).
* **"Make five persona-specific versions of this video from our base template."** Reads the template's design (`get_clueprint`), spawns five copies of a base project (`duplicate_project` × 5), tweaks the voiceover script per persona (`voiceover_batch`), and exports all five (`export_project`).
* **"Repurpose this landscape explainer as a vertical short for Reels."** Clones the project (`duplicate_project`), switches it to a 9:16 aspect ratio so elements reflow onto the portrait canvas (`update_project`), nudges any callouts that drift off-frame (`update_elements`), and exports the vertical cut (`export_project`).
* **"Refresh every onboarding video with our new brand colors."** Walks your workspace (`find` with `type=projects` → `get_project`), updates each clip background and element style in place (`update_clips`, `update_elements`), and re-exports the affected videos (`export_project`).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Clueso connector doesn't appear in my AI assistant">
    * Make sure you've restarted your AI assistant after saving the configuration.
    * For MCP server setups (Cursor, VS Code, and Claude code), verify Node.js 22.16+ is installed by running `node --version`.
    * Check that the MCP server URL `https://connect.clueso.io/mcp` is correct in your config file.
  </Accordion>

  <Accordion title="Authorization keeps failing">
    * Make sure you're logged into Clueso at [web.clueso.io](https://web.clueso.io) in your browser before authorizing.
    * Try clearing your browser cookies and re-authorizing.
  </Accordion>

  <Accordion title="Tool calls time out or return errors">
    * Confirm your Clueso account is active and your workspace is accessible.
    * Check your internet connection and any firewall rules that might block `connect.clueso.io`.
    * Try removing and re-adding the MCP server, then re-authorizing.
  </Accordion>

  <Accordion title="MCP tools don't appear in Cursor or VS Code">
    * In Cursor, make sure you're in **Agent mode**, not normal chat.
    * In VS Code, make sure GitHub Copilot is active and you're in an **Agent chat** (`@workspace` or the agent panel).
    * Restart the editor after any config changes.
  </Accordion>
</AccordionGroup>

***