Set up Clueso 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.

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
- OpenAI Codex CLI
- Gemini CLI
- Cursor
- VS Code (with GitHub Copilot or a compatible MCP extension)
A Clueso account

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

Connect your AI assistant

This setup requires a ChatGPT paid plan (Plus, Pro, Team, Enterprise, or Edu). A paid ChatGPT plan is recommended for better outputs

Open ChatGPT and go to Settings.
Click Apps, then enable Developer Mode.
Click Add (or Create) and enter the following URL: https://connect.clueso.io/mcp
Name it Clueso and save.
A browser window will open — sign in to Clueso and click Allow to authorize.
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.”

Run the following command in your terminal to add the Clueso MCP server to Claude Code:

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.

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.

To verify the server was added:

claude mcp list

You should see Clueso listed with a ✓ connected status.Test it by starting a session:

claude

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

For full Claude Code MCP documentation, see Anthropic’s Claude Code MCP docs.

Remote MCP servers require a recent version of the Codex CLI. Run codex --version to check, and update with npm i -g @openai/codex if needed.

Add the Clueso MCP server to your Codex config at ~/.codex/config.toml:

~/.codex/config.toml

[mcp_servers.clueso]
url = "https://connect.clueso.io/mcp"

Then authorize Clueso:

codex mcp login clueso

A browser window will open — sign in to Clueso and click Allow.Verify by starting Codex and running /mcp — you should see clueso in the list.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.”

Gemini CLI MCP support requires Gemini CLI version 0.1.7 or later. Run gemini --version to check.

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

gemini mcp add clueso https://connect.clueso.io/mcp

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:

~/.gemini/settings.json

{
  "mcpServers": {
    "clueso": {
      "httpUrl": "https://connect.clueso.io/mcp",
      "timeout": 10000
    }
  }
}

Test it:

gemini

“Show me all projects in my Clueso workspace.”

For more on Gemini CLI, see the Gemini CLI GitHub repo.

MCP tools in Cursor are only available in Agent mode. Make sure you’re in an Agent chat session.

Requires Node.js 22.16 or later with npm. Download Node.js →

Option 1 — Automatic setup (recommended)

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

cursor://anysphere.cursor-deeplink/mcp/install?name=Clueso&config=eyJjb21tYW5kIjoibnB4IC15IG1jcC1yZW1vdGVAbGF0ZXN0IGh0dHBzOi8vY29ubmVjdC5jbHVlc28uaW8vbWNwIn0=

Option 2 — Manual setup

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

mkdir -p .cursor && touch .cursor/mcp.json

Add the following to .cursor/mcp.json:

.cursor/mcp.json

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

Restart Cursor to apply the config.
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.”

For more details, see the Cursor MCP documentation.

MCP tools in VS Code require GitHub Copilot (or another compatible MCP extension) and are only available in Agent mode.

Requires Node.js 22.16 or later with npm. Download Node.js →

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

mkdir -p .vscode && touch .vscode/mcp.json

Add the following to .vscode/mcp.json:

.vscode/mcp.json

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

Restart VS Code to apply the configuration.
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.”

For more details, see the VS Code MCP documentation.

Verify the connection

After setup, confirm the Clueso MCP server is working:

Look for the Clueso tool in your AI assistant’s tools or connectors panel.
Run a test prompt, for example:
“Show me my most recently updated Clueso project.”
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.

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.

What you can do with Clueso MCP

Once connected, you can ask your AI assistant to:

Create projects

“Create a new video called ‘How to reset your password’.”

Add voiceovers

“Add a voiceover to the first clip of my onboarding guide.”

Export videos

“Export my ‘Getting Started’ project as a video.”

Update articles

“Update the article in my ‘API Docs’ project with this new content.”

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, backgrounds, AI image-generation styles, saved components, and media (images, videos, music, sound effects). 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')`, `find(type='voices', language='en')`, or `find(type='images', query='city skyline', provider='pixabay', image_type='illustration')`.
`switch_workspace`	Switch the active workspace for the current session.

Two things find reaches beyond your own workspace:

Stock libraries. Media searches cover both your saved library and stock providers, and your assistant picks the library with provider: Pexels for realistic photos and real-world footage (the default), Pixabay for illustrations, vectors, icons and motion graphics (narrowed with image_type or video_type), Clueso’s curated catalog for brand-safe music and sound effects, and Freesound for niche tracks and a vast sound-effect library. Scope the search with source ('org', 'stock', or 'all'), and narrow stock results by orientation, color, size, or clip length.
The community clueprint library. Searching clueprints ranks matches across your workspace and the public community library, so your assistant can start from a template someone else published.

Projects

Tool	What it does
`create_project`	Create a new project. It starts with one blank clip, ready for content.
`get_project`	Read a project’s structure — canvas size, clips, durations, element counts, and audio tracks.
`update_project`	Rename a project, edit its description, move it between folders, or change its aspect ratio.
`duplicate_project`	Clone an entire project into a fresh, independent copy.

Aspect ratio accepts any W:H you ask for, not just the presets — 16:9 for web, 9:16 for Reels/Shorts/TikTok, 1:1 or 4:5 for feed posts, 3:4 for portrait cards. Element positions are stored as fractions of the canvas, so everything reflows onto the new shape automatically when you switch.

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, titles, visibility, or entrance transitions. Can also reorder clips, and reposition, resize, crop or frame the recording inside a video clip.
`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 (everything layered onto a clip)

Tool	What it does
`add_elements`	Place elements onto one or more clips in a single call. Text is auto-measured so it fits its box.
`update_elements`	Edit the position, size, timing, or content of existing elements. Text can be re-fit to a target number of lines automatically.
`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 a code-based animation directly into a clip.

Ten element types are available: text, callout, rectangle, arrow, image, video (picture-in-picture, b-roll or a background loop over an existing clip), animation, plus three built for demo footage — zoom, spotlight and blur (for masking sensitive data on screen).

Elements can be animated. Pass keyframes to add_elements or update_elements to move and resize an element over time, with a choice of interpolation between points.

For AI-generated visuals, generate_media covers both directions: text-to-image (optionally steered by one of your workspace’s generation style presets, or grounded on a reference image) and prompt-to-animation, which can reuse a saved animation as its starting point and time itself against a voiceover script. Generation runs in the background — the element appears immediately and fills in once rendered.

Voiceover and audio

Tool	What it does
`voiceover_batch`	Set voiceover scripts and/or generate AI speech for any number of clips in one call.
`set_voice`	Set the AI narration voice across every clip in a project.
`add_audio`	Add background music or a sound effect that plays across the whole project — from a stock `find` result or an uploaded audio file, with control over volume, fades, timing, trimming, and looping.
`update_audio`	Adjust an existing music or SFX track — volume, fades, timing, or looping.
`analyze_audio`	Inspect an audio file: transcript with word-level timestamps, silent regions, tempo and beat positions, or loudness and duration.

Generating speech re-times the clip to the length of the spoken audio. Ask for the voiceover before placing time-sensitive elements, or use estimate_duration first, so your timings match the final length.

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`	Inspect a screenshot, or edit its zoom, crop, or annotation shapes.

Recording

Tool	What it does
`record_screen`	Have Clueso record your product on screen. Describe the run as a list of scenes — each one narrated or silent b-roll, with its own script, pacing, and voice — and Clueso captures them as clips.

record_screen uses Clueso’s auto-recording agent, which requires a specific plan. If it isn’t part of your plan yet, reach out to our team — via the in-app chat, email, or your shared channel — or visit clueso.io/agents to explore it.

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.

There are three ways to get a file in, and your assistant picks whichever fits where the file lives:

A file on your machine — Clueso returns an upload link and a one-line command; a coding assistant can run it for you.
A file already on the web — pass the URL and Clueso fetches it directly, no interaction needed.
Several files at once — Clueso returns a shareable upload page you open in your browser and drop files onto, then check_uploads collects them all.

Clueprints and design reference

Tool	What it does
`create_clueprint`	Save a project as a reusable clueprint (a video template).
`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.
`get_design_guide`	Read Clueso’s house style for composing clips — concept, typography, color, composition, motion and pacing. Your assistant reads this before designing a clip from scratch, so output looks like Clueso rather than a slide deck.

Collaboration

Tool	What it does
`add_comment`	Leave a review comment on a project, or pin one to a specific clip and timestamp.

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. Defaults to 1080p and 30fps with no captions; ask for a different resolution, frame rate, burned-in captions, or language.

Exports run in the background — your assistant hands back straight away, and the finished video appears in the Exports tab of the editor.

Alongside these tools, the Clueso MCP server publishes reference material your assistant can pull in on demand — how to author a clueprint, how to write animation prompts, how sync points work, how generation styles steer images, and the full property schema for every element type. You don’t need to request these; the assistant reads them when relevant.

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

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.

Authorization keeps failing

Make sure you’re logged into Clueso at web.clueso.io in your browser before authorizing.
Try clearing your browser cookies and re-authorizing.

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.

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.

Getting started

Home

Screen recording

Voiceovers

Sync points

Editing

Elements

Article

Languages and Translation

Account

Release Notes

Before you start

Connect your AI assistant

Option 1 — Automatic setup (recommended)

Option 2 — Manual setup

Verify the connection

What you can do with Clueso MCP

Create projects

Add voiceovers

Export videos

Update articles

Tools available

Find and browse

Projects

Clips

Elements (everything layered onto a clip)

Voiceover and audio

Sync (for video clips with source recordings)

Articles

Recording

Files and assets

Clueprints and design reference

Collaboration

Export

Combine tools for end-to-end workflows

Troubleshooting

​Before you start

​Connect your AI assistant

​Option 1 — Automatic setup (recommended)

​Option 2 — Manual setup

​Verify the connection

​What you can do with Clueso MCP

Create projects

Add voiceovers

Export videos

Update articles

​Tools available

​Find and browse

​Projects

​Clips

​Elements (everything layered onto a clip)

​Voiceover and audio

​Sync (for video clips with source recordings)

​Articles

​Recording

​Files and assets

​Clueprints and design reference

​Collaboration

​Export

​Combine tools for end-to-end workflows

​Troubleshooting

Before you start

Connect your AI assistant

Option 1 — Automatic setup (recommended)

Option 2 — Manual setup

Verify the connection

What you can do with Clueso MCP

Tools available

Find and browse

Projects

Clips

Elements (everything layered onto a clip)

Voiceover and audio

Sync (for video clips with source recordings)

Articles

Recording

Files and assets

Clueprints and design reference

Collaboration

Export

Combine tools for end-to-end workflows

Troubleshooting