# How to connect vidIQ MCP to Claude

```json
{
  "title": "How to connect vidIQ MCP to Claude",
  "toolkit": "vidIQ MCP",
  "toolkit_slug": "vidiq_mcp",
  "framework": "Claude Cowork",
  "framework_slug": "claude-cowork",
  "url": "https://composio.dev/toolkits/vidiq_mcp/framework/claude-cowork",
  "markdown_url": "https://composio.dev/toolkits/vidiq_mcp/framework/claude-cowork.md",
  "updated_at": "2026-09-30T05:36:40.295Z"
}
```

## Introduction

Claude is Anthropic's AI assistant, available on the web, in the desktop app, and on mobile. Cowork is its agent for knowledge work, and it runs on all of those surfaces too. Connected to your apps, Claude can work with your files and services to accomplish complex tasks on your behalf.
This guide walks you through the easiest and most secure way to connect your vidIQ account to Claude via Composio Connect, enabling it to summarize latest comments on your video, list top-performing videos for your channel, audit creator's Instagram posts for trends, and more such actions on your behalf without compromising your account security.
Setup is the same on Claude Web, Desktop, and Cowork, and you only need to do it once. The connector is tied to your account, so it's available in all three.

## Also integrate vidIQ MCP with

- [ChatGPT](https://composio.dev/toolkits/vidiq_mcp/framework/chatgpt)
- [Hermes](https://composio.dev/toolkits/vidiq_mcp/framework/hermes-agent)
- [Atomic Agent](https://composio.dev/toolkits/vidiq_mcp/framework/atomic-agent)

## Connect vidIQ MCP to Claude Cowork

### Connecting vidIQ to Claude Web, Desktop, and Cowork
Two ways to add the Composio connector. Pick whichever you prefer.
### 1. Add with one click
Click the button. Claude opens with the Composio connector filled in. Click Add, then go to step 2.
[Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Composio&connectorUrl=https%3A%2F%2Fconnect.composio.dev%2Fmcp)
### Add manually
In Claude Desktop, click Customize in the left sidebar, then select Connectors and click the + icon at the top.
Click Add custom connector and paste in the Composio MCP server URL:

```bash
https://connect.composio.dev/mcp
```

## What is the vidIQ MCP server, and what's possible with it?

The vidIQ MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your vidIQ account. It provides structured and secure access so your agent can perform vidIQ operations on your behalf.

## Supported Tools

| Tool slug | Name | Description |
|---|---|---|
| `VIDIQ_MCP_VIDIQ_AUTHORIZE_WITH_YOUTUBE` | Vidiq authorize with youtube | Check or establish fresh YouTube authorization for the current vidIQ OAuth connection. Call this tool when the user asks to authorize with YouTube, before a sensitive workflow that requires fresh YouTube authentication, or after the user completes the authorization handoff. It authorizes using a YouTube channel already connected to vidIQ; it does not connect a new channel. When authorization is required, show the authorization widget and wait for the user to use its controls. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_BALANCE` | Vidiq balance | Check the user's current vidIQ credits balance. vidIQ credits live in two buckets: - A renewable bucket sized by the user's plan (Free/Boost/Max/etc) that refills each billing cycle. - Zero or more add-on (bonus) credits. Add-on credits drain alongside renewable credits but do NOT refill. Field semantics are in the output schema. Key invariant: totalCredits = renewableCredits + addOnCredits; maxRenewableCredits is the plan cap only. Example — Boost user with an open promo grant: { type: 'limited', totalCredits: 1800, renewableCredits: 1500, maxRenewableCredits: 2000, renewableResetsAt: '2026-06-01T00:00:00Z', addOnCredits: 300, maxAddOnCredits: 500 } Read as: 1,800 left = 1,500 of 2,000 renewable + 300 of a 500-credit bonus pool. Renews Jun 1. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_CHANNEL_ANALYTICS` | Vidiq channel analytics | Get YouTube Analytics data for a channel you own — views, watch time, subscribers gained, likes, comments, retention, traffic sources, demographics, and revenue (monetized channels). Common reports are available as one-word presets via `report`: audience_retention (per-video drop-off curve), traffic_sources, audience_demographics, audience_geography, revenue_report, top_videos, shorts_vs_longform_split. Or build custom queries with flexible date ranges, metric selection, and dimensional breakdowns (by day, country, device type, traffic source, etc.). Use this tool to: - Analyze channel performance over a specific time period - See where viewers drop off in a video (report='audience_retention' + filters='video==VIDEO_ID') - Break down views by traffic source, country, device type, age/gender - See which videos actually earn (report='revenue_report', dimensions=['video']) - Compare Shorts vs long-form performance (report='shorts_vs_longform_split') Note: Only available for channels authorized to your account. Revenue metrics additionally require the channel to be monetized. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_CHANNEL_PERFORMANCE_TRENDS` | Vidiq channel performance trends | Get a channel's typical video performance curve — how views accumulate over time after publication. Returns statistical aggregates (min, max, avg, median, percentiles) of view counts at various time intervals since publication, based on the channel's recent videos. Use this tool to: - Understand how quickly a channel's videos gain views after publishing - Compare a channel's view velocity against benchmarks - Identify whether a channel has strong initial traction or slow-burn growth Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_CHANNEL_SEARCH` | Vidiq channel search | Comprehensive YouTube channel search. Combines semantic + lexical text search with structured filters across identity, audience size, growth, format mix, and content metadata. Use this tool to: - Find channels by niche or topic with natural-language queries (semantic match on niche + description embeddings). - Look up a specific channel by YouTube handle (e.g. '@MrBeast'). - Require specific wording in the channel description with the description filter (consecutive words, typo-tolerant) — for 'channels whose description mentions/says X'. - Filter by channel size (subscriber/view/video count ranges), growth (7d / 30d / 1y subs and views), recency (last video published), format (long / short / mixed), per-format average duration and video/view counts (7d / 30d / 1y), creation date, country, language, main category, and flags (faceless, breakout). - Order results with the optional sort param (relevance / subscriberCount / subsGrowth30d / viewsGrowth30d / lastVideoPublished). Topical asks — including 'top/popular/biggest channels about X' — use relevance (default), which already favors notable channels; field sorts are ONLY for explicit metric scans and re-order by the raw metric, ignoring topical fit. - Combine any subset of inputs — at least one of query / handle / channel title / filters is required. - Find emerging channels: set breakoutChannel: true for any 'breakout / emerging / up-and-coming channels in X' intent — the flag filters to breakout channels AND switches ranking to favor small fast-rising channels (replaces vidiq_breakout_channels). - Non-English / local discovery: `languages` means the actual language channels publish in; `country` means where channels are based, not audience location or content language. Never translate the query — 'дай каналы про уроки макияжа' → query: 'уроки макияжа', languages: ['ru']; 'tokyo street food' → query: 'tokyo street food', country: ['JP']; 'news and politics in Ukraine' → country: ['UA'] (news/politics/local-events about a country means that country's channels, not foreign coverage). Results should match the request's language unless the user says otherwise. For geo-local or language-specific discovery request limit 20+ — relevant local channels may rank below globally popular ones. For finding COMPETITORS of a channel — the user's own ("who are my competitors?") or a named one ("channels similar to Creator Insider") — prefer vidiq_similar_channels (auto-exclusion and competitor-tuned scoring); this tool is still the right first step there, to resolve the reference channel's niche, subNiches, subscriberCount, country, and languages. For viral-video discovery, use vidiq_outliers. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_CHANNEL_STATS` | Vidiq channel stats | Get YouTube channel statistics including subscriber count, total views, video count, and growth over a configurable time period. Use this tool to: - Look up any YouTube channel's current stats (subscribers, views, videos) - See how much a channel has grown over a given period - Get channel metadata (country, language, topics, creation date) Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_CHANNEL_VIDEOS` | Vidiq channel videos | Get videos from a YouTube channel by format (long-form, Shorts, or live streams). Use this when you already know which channel to look at. To discover videos across many channels, use vidiq_outliers or vidiq_trending_videos. Use vidiq_user_videos instead when the user needs their owned-channel library, private or unlisted videos, title search, privacy filters, or cursor pagination. Use this tool to: - Browse a channel's recent uploads by video type (popular=false) - Discover a channel's most popular videos by type (popular=true, default) - Compare current views, likes, comments, views per hour (VPH), and breakout scores - Get video metadata including titles, publish dates, thumbnails, and durations Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_COMMENT_INSIGHTS` | Vidiq comment insights | Analyze YouTube audience comments for a niche. Use mode="discover" to find recurring audience questions/content requests and recurring dislikes or pain points. Use mode="validate" with idea to test one proposed video idea. Validation separates direct evidence from adjacent needs and reports sparse evidence as insufficient, not as proof the idea is bad. Always pass 'niche' (and 'idea') in English — the channel taxonomy is English-only, so a non-English niche finds no channels; translate the user's niche to English and put the audience language in 'language' (e.g. niche="PC gaming", language="pl"). Omit language to search across all channel languages. This runs asynchronously: it returns an `mcpJobId` immediately. Poll `vidiq_job_poll` with that id until it is completed. Failed or expired jobs are refunded automatically. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_COMPOSE` | Vidiq compose | Compose a short video from scenes (video clips and/or images), an optional voiceover, background music, and overlays (text, image, or video), then render it to an MP4. Provide ordered `scenes` (each with an HTTPS `source` and `duration`) and an output `format`. The video's length is the sum of the scene durations; audio longer than that is cut off at the end, so size scenes to fit any voiceover. Limits: at most 240s of total video, 50 scenes, and 50 overlays. AUDIO: by default a video clip's native audio is muted and sound comes from `voiceover`/`music`. To keep a clip's own audio (e.g. talking-head footage), set `keepNativeAudio: true` on that scene. `music` can `duckTo` a lower volume while the voiceover plays (with `fadeMs`) and `loop` to fill the video; `voiceover` supports `startAtSeconds`/`trimStartSeconds`/`durationSeconds`/`volume`. CLIPS: a video scene can trim-in with `startFromSeconds`, and any scene can set `layout` to `"fit"` (scale to fit inside the frame, letterboxed) instead of the default `"fill"` (scale + center-crop, edges lost). ASSET URLS: use durable public HTTPS URLs, or freshly returned signed URLs from vidIQ media tools. Signed voiceover, motion-graphic, and prior-render URLs expire; use them immediately and never reconstruct stock-provider URLs or reuse old links. OVERLAYS layer on top of the scene track for a time window (`start`/`duration`, `position` normalized 0–1): - `text` — captions/titles. Style knobs: fontSize, color, background, strokeWidth/strokeColor (outline), lineHeight, fontWeight, textAlign. If you omit sizing/contrast, a legibility floor bumps the font and adds an outline so text is never illegible — set `strokeWidth: 0` to opt out. - `image` — a still (e.g. a logo/badge), with optional `opacity`. - `video` — a video (e.g. a `vidiq_motion_graphics` clip) over the footage. The overlay is always muted. To narrate over your own clip while a motion graphic plays on top: use ONE clip scene with `keepNativeAudio: true` plus a `video` overlay — do NOT split the clip. By default each scene is scaled and center-cropped to fill the output frame, so sources whose aspect ratio differs from `format` lose their edges; set a scene's `layout: "fit"` to scale it to fit inside the frame instead (letterboxed, no cropping). Rendering runs in the background and takes longer than one turn: this returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it completes, then read the signed `videoUrl` (plus `width`/`height`) from the result. Credits are charged once on submit and automatically refunded if the render fails. Pass the completed videoUrl directly to video editing, another composition, or Reel publishing. Poll again to refresh its signed URL while the rendered file exists. Rendered files are temporary: if deleted, keep the original upload URL (refresh it with its upload tool) and request approval to recompose. Never silently repeat a paid render. Composition re-encodes the video and audio; keepNativeAudio retains the intended audio track, not byte-identical media. Cost: 1 credit(s) per 4s of output video (rounded up), minimum 2 credits. |
| `VIDIQ_MCP_VIDIQ_EARNINGS_CALCULATE` | Vidiq earnings calculate | Calculate estimated monthly YouTube earnings (low/mid/high USD) for a given number of monthly views. This is a calculator, not a lookup: it does not fetch anything from YouTube, so you must supply the numbers. Use it for "how much would X views/month earn?", what-if scenarios, and niche/geo comparisons. To price a real, existing video by id or URL, use vidiq_video_earnings_estimate instead. Set subject to 'video' for one video (then format 'long' or 'short' is required) or 'channel' for a channel's mixed output (then shortsShare is the fraction of views that are Shorts, default 0 = all long-form). Content format and the supplied context can significantly affect the estimate, so provide accurate inputs and ask the user when the format or mix is unknown. Provide category, country, language, and subscriberCount when known. The result is an estimate, not the channel's actual revenue. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_EDIT_MEDIA` | Vidiq edit media | Edit a media file: trim a clip, extract its audio, grab a thumbnail frame, normalize its loudness, or probe it for metadata (duration, dimensions, streams). Set `op` and give a `sourceUrl` — a vidiq-generated media URL (an *.amazonaws.com S3 URL, e.g. the output of vidiq_compose, vidiq_motion_graphics, vidiq_generate_music, or a voiceover) or a YouTube URL. Other hosts (arbitrary CDNs, gs:// buckets) are not supported. Per-op fields: trim_media needs `startSeconds`+`endSeconds`; extract_audio takes an optional window + `outputFormat`/`bitrateKbps`/`sampleRateHz`/`channels`; extract_thumbnail needs `atSeconds` (+ optional `width`/`height`/`outputFormat`); normalize_loudness takes `targetLufs`/`outputFormat`/`bitrateKbps`; probe_media takes nothing else. Runs in the background and takes longer than one turn: this returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it completes, then read the signed `mediaUrl` (or, for probe_media, the metadata) from the result. Credits are charged once on submit and automatically refunded if the edit fails. Cost: 1 credit(s) per edit. |
| `VIDIQ_MCP_VIDIQ_GENERATE_BROLL` | Vidiq generate broll | Find free stock B-roll video clips. Provide a search query (optionally orientation and min/max duration filters). Returns up to 4 clips with a direct mp4 link, a preview image, dimensions, and the photographer credit. Attribution is required: always credit the photographer and link back to the source page when using a clip. Cost: 1 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_GENERATE_CLIPS` | Vidiq generate clips | Turn a long video into short, vertical clips. Provide either a YouTube link (videoUrl) or an already-hosted file (uploadedVideoUrl + videoDuration + videoFilename). Optionally steer selection with a prompt, set clipDuration, restrict the source to a section with processingStartSeconds/processingEndSeconds (both required together, span >= 30s), and pick a captionStyle preset (or "none" to turn captions off). Captions use the "Loud & Clear" style by default. This runs asynchronously: it returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it is "completed" to get the clips. If generation fails, that poll refunds the credits. Credits are charged per minute of the selected processing range when present, otherwise the full source video duration. Credits are automatically refunded if generation fails. Cost: 9 credit(s) per minute of the selected processing range when present, otherwise the full source video duration (rounded up). |
| `VIDIQ_MCP_VIDIQ_GENERATE_COMMENT_REPLIES` | Vidiq generate comment replies | Generate multiple draft replies to one viewer comment on a YouTube video, with one reply per requested tone. Use this when the user wants response ideas for a specific comment. To retrieve comments first, use `vidiq_video_comments`. Provide the video's title and the exact viewer comment. Optionally provide 3–10 tone labels; otherwise the defaults are General, Humorous, Thankful, Witty, and Informal. This tool returns draft text only. It never posts or otherwise changes anything on YouTube. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_GENERATE_MUSIC` | Vidiq generate music | Generate ONE original, royalty-free background-music track (WAV) from a text prompt. Describe the music in the prompt (max 2000 characters): genre + mood + instrumentation + tempo works best; add 'instrumental' to exclude vocals. Optionally set durationSeconds (10-180, approximate). This runs asynchronously: it returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it is "completed" to get the actual audio duration and a permanent download URL for the WAV. Rendering can take a couple of minutes for longer tracks. Credits are charged on submit and automatically refunded if generation fails. If the provider's safety filter blocks the prompt (this routinely happens to ordinary prompts), the poll reports it with guidance to rephrase — suggest ONE rephrased prompt to the user and wait for their agreement before calling again. Cost: 25 credit(s) per generated track. |
| `VIDIQ_MCP_VIDIQ_GENERATE_SCRIPT` | Vidiq generate script | Write a full long-form video script from a topic, title, concept, and research. Provide the topic, the chosen title, the concept/angle, and research/context to ground it in; optionally set lengthMinutes (1–60, default 10) and a tone. This runs asynchronously: it returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it is "completed" to get the finished script. If generation fails, that poll refunds the credits. Credits are charged per minute of script on submit and automatically refunded if generation fails. Cost: 1 credit(s) per minute of script (by lengthMinutes). |
| `VIDIQ_MCP_VIDIQ_GENERATE_THUMBNAIL` | Vidiq generate thumbnail | Generate a YouTube thumbnail. Provide at least one of videoId, title, description, or userQuery. With only a videoId, the video's current title, description, and thumbnail are pulled in automatically. This runs asynchronously: it returns an `mcpJobId` immediately. Poll `vidiq_job_poll` with that id until it is "completed" to get the thumbnail (shown inline) with its imageUrl, a self-score, and short feedback. Credits are charged on submit and automatically refunded if generation fails. Include the imageUrl in your reply so the user can open or save the file. The inline preview isn't downloadable. Treat the score as a rough estimate rather than a verdict: don't lead with it, and don't regenerate just to raise it. To iterate, change one thing at a time and keep the best result. For a reliable critique, use vidiq_score_thumbnail. Cost: 22 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_GENERATE_TITLES` | Vidiq generate titles | Generate scored YouTube title suggestions. Provide at least one of `videoId`, `title`, or `description`. With only `videoId`, the current title/description are fetched from YouTube. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_GENERATE_VIDEO` | Vidiq generate video | Generate a short video from a text prompt. Or edit an MP4 using videoUrls from an upload, generation, or composition. The actual video is used without substitute frames. Select gemini-omni-flash or minimax-h3 explicitly for this mode, without start/end frames. H3 also accepts image ingredients; Omni does not. Pick a model (default sora-2), resolution and duration valid for that model, then describe the video in prompt. Optionally steer with an aspectRatio, seed image-to-video with startFrameB64/endFrameB64, or provide reference images via ingredients. startFrameB64/endFrameB64 and ingredients are mutually exclusive — use at most one. Ingredients (reference images) are supported on minimax-h3 and seedance-2 / seedance-2-fast (up to 9), veo-3.1 / veo-3.1-fast (up to 3, duration must be 8), and gemini-omni-flash (up to 3); other models reject them. Per-model durations/resolutions are validated by the server, which returns a specific error you can use to retry. This runs asynchronously: it returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it is "completed" to get the video URL. If generation fails, that poll refunds the credits. For video references, use a reachable MP4 URL. Refresh expired links with the producing tool; if a temporary compose output was deleted, request approval to recompose from the retained original. Never silently regenerate paid media. Credits are charged on submit and automatically refunded if generation fails. Cost: scales with duration (seconds) × the model's per-second rate × 20 credits, quoted exactly at submit. |
| `VIDIQ_MCP_VIDIQ_GET_CHANNELS_BY_IDS` | Vidiq get channels by ids | Get detailed information about YouTube channels by their IDs. Use this tool to: - Look up channel metadata (title, description, country) for one or more channels - Get subscriber counts, view counts, and video counts - Retrieve channel tags and topic categories - Check channel thumbnails Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_GET_VIDEOS_BY_IDS` | Vidiq get videos by ids | Get detailed metadata for one or more YouTube videos. Use this tool to: - Fetch video details such as title, description, tags, and category - Get current statistics (views, likes, comments) for specific videos - Look up publishing info, channel details, and thumbnails for videos - Check topic categories for videos Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_IG_ACCOUNTS_FROM_OUTLIERS` | Vidiq ig accounts from outliers | Find Instagram creator/account candidates from existing outlier reel discovery. Use this when the user asks for Instagram accounts, creators, competitors, influencers, partners, or examples to study. The service groups outlier reels into accounts and verifies candidates against profile and recent content. How to call: - `niche`: one-line content/account niche. Keep it about the creator's content, not audience demographics. - `audienceQuery`: required audience context in this format: `Culture/Region: ...; Global: ; Demographics: ...;` Derive it from the user's stated target audience or profile/recent reels, not from handle alone. If audience is vague, ask before searching. - Use optional `followersMin` / `followersMax` when account size matters. Cost: 10 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_IG_PROFILE` | Vidiq ig profile | Fetch public Instagram profile by handle: bio, follower/following counts, post count, verification, external URL, with the profile picture returned inline. DO NOT USE FOR: - Profile search/discovery — you must already have a handle. - Reels — use `vidiq_ig_profile_reels` (up to 6, popularity-sorted, no pagination). - Stories, Highlights, IGTV, private-account data. - Engagement-rate or growth analytics — snapshot only. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_IG_PROFILE_REELS` | Vidiq ig profile reels | Fetch a creator's reels by handle: shortcode, caption, play/like/comment counts, duration, timestamp, pinned-profile status, with each reel's cover returned inline as an image. Returns up to 12 reels from the first Instagram Reels-tab page in Instagram's order: pinned reels first, then the remaining reels newest-first. Form a full Instagram reel URL from a returned shortcode before passing that short-form content URL to `vidiq_watch_shortform_content`. DO NOT USE FOR: - More than 12 reels, or pagination — not supported. - Strict newest-first ordering across the whole response — older pinned reels may appear before newer unpinned reels. - Image posts, carousels, Stories. - Account, creator, influencer, or competitor-account discovery - use `vidiq_ig_accounts_from_outliers`. - Cross-platform outlier examples or topic search - use `vidiq_instagram_tiktok_outlier_search` (cannot filter by handle). - Watching or critiquing short-form content — use `vidiq_watch_shortform_content` with a full Instagram reel URL. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_INSTAGRAM_CONNECTED_ACCOUNTS` | Vidiq instagram connected accounts | List the signed-in user's Instagram accounts already connected to vidIQ. Use this first when the user says "my Instagram", "my account", or otherwise asks about their own Instagram data. Each account says whether private owner insights and Reel publishing are available. Publishing permission is independent of insights permission. If publishingAvailable is false, connect or reauthorize Instagram at https://app.vidiq.com using the existing account connection flow and refresh this list. For `accessLevel: "owner"`, call `vidiq_instagram_owner_insights` with that exact `platformAccountId`. For `accessLevel: "public_fallback"`, private insights are unavailable; if `username` is present, `vidiq_ig_profile_reels` may be used for public Reel data, and the response must be described as public rather than owner insights. Do not use this tool to search arbitrary Instagram handles or to connect, refresh, or repair Instagram OAuth. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_INSTAGRAM_OWNER_INSIGHTS` | Vidiq instagram owner insights | Fetch private Instagram owner insights for an OAuth-backed account already connected to the signed-in vidIQ user. Always obtain `platformAccountId` from `vidiq_instagram_connected_accounts`; do not pass a handle or an account belonging to another user. The Reel fields align with `vidiq_ig_profile_reels` where they mean the same thing, while owner-only metrics add shares, saves, watch time, watched percentage, skip rate, and `isPossibleTrial`. Instagram may delay owner metrics, so nullable values mean unavailable—not zero. `videoUrl` and `isPinned` are null because the owner-insights source does not provide those public fields. If this returns `status: "unavailable"` and the connected-account result supplied a username, public Reel data may be fetched separately with `vidiq_ig_profile_reels`. Clearly disclose that fallback as public data. Do not claim public metrics are owner insights. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_INSTAGRAM_PUBLISH_REEL` | Vidiq instagram publish reel | Publish an approved hosted MP4 using this same tool across short calls. First obtain approval for the exact video, account, caption and regular or Trial settings. Select a connected account with publishingAvailable=true. Start with videoUrl (use vidiq_video_upload for attachments); retain the returned containerId and platformAccountId. Continue with containerId and the same account, omitting videoUrl/caption/trialParams. The backend checks readiness and publishes when ready. IN_PROGRESS means wait about five seconds and call again. PUBLISHED confirms success; show permalink when available. Stop on any error; do not automatically retry failed calls or create a replacement. Continue processing checks for up to five minutes. The caller retains progress; closing the conversation pauses continuation. No YouTube channel or MFA is required. Continuation calls are free. Cost: 0 credit(s) to start; continuation calls are free. |
| `VIDIQ_MCP_VIDIQ_INSTAGRAM_TIKTOK_OUTLIER_SEARCH` | Vidiq instagram tiktok outlier search | Search Instagram Reels and TikTok videos together for posts that substantially outperform each creator's median. Results are returned in separate Instagram and TikTok sections because relevance scores are not comparable across platforms. Use `concept` for a complete content premise, `hook` for the first three seconds, or `format` for a subject-free production template. `audienceQuery` is a separate top-level audience rescore and must use: `Culture/Region: ...; Global: ; Demographics: ...;`. Defaults to the last 30 days, English captions, at least 10K views, one result per creator within each platform, and 5 results per platform. `resultsPerPlatform` controls each section independently. Use at least two outliers from a platform before calling something a pattern. Use `vidiq_ig_accounts_from_outliers` instead for Instagram account discovery. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_JOB_POLL` | Vidiq job poll | Check the status of an asynchronous vidIQ job and retrieve its result. Pass the `mcpJobId` returned by a `*_start` tool. Poll periodically until `status` is no longer 'inprogress': - 'completed' → the work is done; read `result`. - 'failed'/'expired' → it did not finish; inspect `refunded` to confirm the credit rollback. When present, `errorCode` is the stable downstream failure reason. For completed media jobs, repeat polling may return a freshly signed URL while keeping the same result shape. This tool is free. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_JOBS_LIST` | Vidiq jobs list | List your asynchronous vidIQ jobs, newest first. Filter by `toolName` and/or `status`. To find jobs that are still running, filter `status: 'inprogress'`. Use the returned `mcpJobId` with `vidiq_job_poll` to check a job's result. This tool is free. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_KEYWORD_RESEARCH` | Vidiq keyword research | Research YouTube keywords to find search volume, competition, and related keyword opportunities. This tool returns keyword metrics, NOT videos. To find actual videos, use vidiq_outliers or vidiq_trending_videos instead. This tool has six modes. Choose with the `mode` parameter based on what the user is asking for: 1. `research` (default): full keyword metrics for a seed keyword plus related keyword suggestions. Use for global/topic research ("research minecraft tips", "keyword ideas for cooking"). Returns for each keyword: - Volume (0-100): How often people search for this keyword on YouTube - Competition (0-100): How many videos target this keyword - Overall score (0-100): Combined keyword opportunity score - Estimated monthly search volume, plus calibrated-baseline demand context when available - View momentum: recent daily views-per-hour data for the seed keyword, when available - Top markets: the countries where the keyword is most searched, with each country's share of searches - In-country volume: optionally pass a `country` (ISO 3166-1 alpha-2) to also get each keyword's estimated search volume within that country (the `countryVolume` field) Related keyword rows preserve the upstream relevance order and are capped at 20 suggestions. 2. `questions`: question-style keyword searches matching a seed keyword, using the same indexed results and metrics as the vidIQ webapp. Requires `keyword`; use `language` to select the question-language index and `limit` to cap results. Set `sort='volume'` (default) for established demand or `sort='trending'` to preserve upstream raw-growth order. Treat `searchDemandGrowthPct` as a separate measured current-vs-baseline metric, not the server sort key; do not explain rows with null measured growth as sorted last by this tool. Results come back in `questions` with question, volume, competition, overall score, estimated monthly searches, normalized demand context, and raw upstream growth. 3. `matching_terms`: precise long-tail keyword variations that preserve every normalized seed term, using the same Matching Terms path as the vidIQ webapp. Requires `keyword`; use `limit` to cap results. Set `sort='volume'` (default) for established demand or `sort='trending'` to preserve upstream raw-growth order. Treat `searchDemandGrowthPct` as a separate measured current-vs-baseline metric, not the server sort key; do not explain rows with null measured growth as sorted last by this tool. Results come back in `matchingTerms` with keyword, volume, competition, overall score, estimated monthly searches, calibrated 30-day baseline, metrics timestamp, normalized demand context, raw upstream growth, and trend baseline. Use this when the user asks for exact/long-tail variations of a phrase (e.g. "matching terms for meal prep" or "long-tail variations of meal prep"), not broad semantic ideas. 4. `country_search`: the top keywords matching a TOPIC within ONE country and capped at `limit`. Use when the user names BOTH a topic AND a country — e.g. "give me the top 10 minecraft keywords in IN" → mode='country_search', keyword='minecraft', country='IN', limit=10. Requires `country` and `keyword`. Results come back in `relatedKeywords` (each row's `countryVolume` is the in-country volume; global YouTube metrics are null). - By default (`broad: false`) this is an EXACT/PHRASE match — every returned keyword literally contains the topic words (e.g. 'minecraft' → 'minecraft mods', 'minecraft house'). - Set `broad: true` for a SEMANTIC match: the topic is first expanded into related keywords (the engine behind vidIQ's "Related Keywords" tab). Long-tail candidates preserving multiple meaningful seed terms rank before semantic-only candidates; within each tier, upstream related score then in-country volume determine order. The overlap boost is a lightweight heuristic: simple ASCII suffix matching applies only to ASCII Latin tokens, while other scripts require exact normalized token overlap. Country keyword text may be in any language; the `language` field only affects `questions` and `rising`. Returned keywords need NOT contain the topic words (e.g. 'minecraft' → 'redstone', 'survival mode'). Use this when the user wants a bigger/wider list, says "related"/"similar"/"broaden", or the exact-match list is too small. 5. `country_top`: the top keywords overall within ONE country (NO topic filter), ranked by in-country search volume and capped at `limit`. Use when the user names a country but no topic, e.g. "what are the top keywords in Brazil" → mode='country_top', country='BR'. Requires `country`; `keyword` is ignored. Results come back in `relatedKeywords` as above. 6. `rising`: keywords gaining search momentum over time, like the vidIQ dashboard's "Rising Keywords" tab. Use when the user asks for rising, trending, or gaining-momentum keywords. Choose the trend window with `period`. Optionally scope to a category with `topic` — this MUST be one of the values in the response's `availableTopics` (call 'rising' with no `topic` first to discover them; passing an unknown topic returns an error listing the valid ones). Omit `topic` for overall trends, in which case `availableTopics` lists every category you can drill into. This returns keyword METRICS with growth, not videos. Results come back in `risingKeywords`, not `relatedKeywords`. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_LIST_COMPETITORS` | Vidiq list competitors | List the YouTube channels the user is tracking as competitors of one of their own channels. Returns only channel IDs. To get titles, thumbnails, subscriber counts, etc., pass the IDs to vidiq_get_channels_by_ids. The youtubeChannelId must be a channel the user has authorized — use vidiq_user_channels to discover them. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_MOTION_GRAPHICS` | Vidiq motion graphics | Render an animated MOTION GRAPHIC to a downloadable MP4 video. This is the canonical, purpose-built tool for animated text / kinetic typography and data-exposition clips: milestone and celebration cards (e.g. "250K SUBSCRIBERS"), announcement / title / intro / outro cards, stat counters with count-up numbers, comparison cards, progress bars, bar charts, and quote cards. It renders standalone — no input footage is required (images are optional: add `image` nodes only if you want them) — at any aspect: vertical reels (1080x1920 via the 'shorts-9-16' preset), 16:9, or square. Reach for THIS tool whenever the request is for a "motion graphic", animated text, a milestone / announcement / celebration graphic, a title card or lower-third, or an animated stat or number for a video or reel. Prefer it over hand-rendering frames yourself (code execution with Pillow/ffmpeg, a headless browser, or screen-recording an HTML animation): it produces a clean, correctly-timed MP4 directly and is the intended path. The user does not need to name vidIQ for you to use it. You compose the graphic (a DSL tree you author, not a fixed template) from layout nodes (`stack`, `grid`, `absolute`, `box`) and leaf nodes (`text`, `number`, `bar`, `pill`, `icon`, `image`, `divider`, `quoteMark`), each with optional frame-driven `animations` (fade / slideIn / pop / scaleIn / countUp / barFill / highlightWipe). Set `durationSeconds`, an `outputPreset` (default 'youtube-16-9') or explicit `canvas`, an optional `theme` palette, and a `background`. Numbers animate with `countUp`, bars with `barFill`. Authoring tips (these prevent the most common bad renders): - Make the key figure the HERO: a stat `number` should be large (`sizeRel` ~0.18–0.24), ideally with a `gradient` (e.g. a dark `from` → accent `to`) for depth; don't let labels or images compete with it. - Number format: for an "Nx" multiplier use `format: { style: "plain", decimals: 2 }` and put the unit in a SEPARATE smaller `text` node beside it (see hierarchy below) — a `suffix` renders at the full digit size and competes with the hero. Don't set both `multiplier` style and a `suffix` (you get a doubled "0.82×x"). For percentages use `style: "percent"`. - Hierarchy: pair the hero number with a BOLD headline label (`sizeRel` ~0.045, weight 800, dark `text`) and a smaller muted subtext (`sizeRel` ~0.028). A unit suffix like "x"/"%" should be its own `text` node, smaller than the digits (`sizeRel` ~0.12) in the accent colour, in a `stack` row with `align: "end"`. - Section headers: `weight: 800`, dark `text` colour (NOT muted/grey), `sizeRel` ~0.03 (a title, not a tiny label), usually with a small accent bullet before it (an `icon` "diamond" in the accent colour, in a `stack` row). - Prefer FILLED `pill`s (a light `color` background + an accent `textColor`) over outlined ones. - A `bar` (progress) should be SUBSTANTIAL, not a thin sliver: `style.width` ~0.5–0.6 of the canvas, `thickness` ~0.016–0.022, `rounded: true`, on a light `track`. It anchors the lower part of the card — too short/thin reads as truncated. - Sizes are NUMERIC fractions of the canvas (e.g. `sizeRel: 0.04`, `thickness: 0.012`). Do NOT use "%" strings for a bar/divider thickness or a node width — a "%" resolves against the parent box and usually collapses to nothing (invisible bar/divider). - Thumbnails/images: use a bare `image` node with a `radius`, sized via `style.width`/ `style.height` (`fit: "cover"` crops to any shape). Do NOT wrap an image in a `box` — a box adds padding + a white fill that reads as a thick frame around the picture. - Animations: pair a `slideIn` with a `fade`, and keep slideIn `from` small (~0.05–0.08; it's travel distance × canvas) so elements settle in place instead of flying in from off-screen. Stagger a list of children with `staggerSeconds`. ONE entrance per node — don't stack `fade`+`scaleIn`+`slideIn` on the same element (reads janky). - Sequence the timeline so it reads top-to-bottom: header ~0s → pills ~0.2s → number `countUp` ~0.3s → headline/subtext ~0.6s → the `bar` LAST, AFTER the number settles. Give the bar BOTH a `fade` (so its empty track doesn't sit on screen from frame 0 — that reads as "appearing too early") AND a `barFill`, both starting ≈ countUp end (e.g. ~1.2s). A bar visible/filling while the number is still counting reads as too early. - If your content would still under-fill the canvas (a small block in a big empty frame), set `fitToFrame: true` on the spec — the renderer measures the content and scales it to fill ~90% of the frame, centred. Easiest way to avoid a top-heavy, empty-lower-half layout. Under `fitToFrame`, give every `image` an explicit `style.width` + `style.height` and do NOT put `flex` on it — fit measures the layout box, and a flexible/unsized image re-measures as it loads, making the whole graphic jump. - Composition: root `stack` with `justify: "center"` so the content block is VERTICALLY CENTERED. Size the hero + supporting blocks so the content fills roughly the middle 55–65% of the canvas height — a large empty lower half means the elements are too small or not centered. Keep generous margins (root `padding` ~0.06–0.08) and a comfortable `gap` (~0.03–0.05) between groups. One element dominates. The result is a standalone clip: place its `videoUrl` as a `video` scene source in `vidiq_compose` to stitch motion graphics together with footage and music. Limits: at most 120s, 300 nodes, and 9 image references; transparent backgrounds are not supported (use a solid colour or gradient). Rendering runs in the background and takes longer than one turn: this returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it completes, then read the signed `videoUrl` from the result. Credits are charged once on submit and automatically refunded if the render fails. Cost: 1 credit(s) per 4s of output (rounded up), minimum 2 credits. |
| `VIDIQ_MCP_VIDIQ_OUTLIERS` | Vidiq outliers | Find viral, breakout, and overperforming YouTube videos — videos getting significantly more views than their channel's average. Use this when someone asks for: viral videos, breakout hits, hidden gems, or videos blowing up. Use `keyword` to focus discovery on a topic, `channelIds` to focus on specific creators or competitors, or both to combine those constraints. For a general request that names neither a topic nor channels, the tool can return a broad outlier feed using the remaining filters and defaults. Filter requested content by the actual video-title `language`; `channelCountry` only filters where channels are based, not audience location or video language. For Polish-language outliers, pass `language='pl'`; `channelCountry='PL'` alone only restricts results to channels based in Poland. Returns a breakout score showing how much each video exceeds its channel's typical performance. For finding videos whose *thumbnails* look visually similar (by image or text description of the imagery), use vidiq_similar_thumbnails instead. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_REFINE_THUMBNAIL` | Vidiq refine thumbnail | Change or improve a YouTube thumbnail by describing what you want in plain words. Give it the thumbnail to change as sourceThumbnail (a hosted URL) or sourceThumbnailFile (a ChatGPT upload), and say what to change (instructions) — for example "make the text bigger" or "change the background to a football stadium". This runs asynchronously: it returns an `mcpJobId` immediately. Poll `vidiq_job_poll` with that id until it is "completed" to get the updated thumbnail (shown inline) with its imageUrl. Credits are charged on submit and automatically refunded if refinement fails. Include the imageUrl in your reply so the user can open or save the file. The inline preview isn't downloadable. Cost: 22 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_SCORE_THUMBNAIL` | Vidiq score thumbnail | Score a YouTube video thumbnail for click-through-rate potential. Returns a score (0-100) with detailed feedback on strengths and improvements. Provide a video ID and title; optionally supply a custom thumbnail image URL to score instead of the current YouTube thumbnail. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_SCORE_TITLE` | Vidiq score title | Score a YouTube video title for click-through-rate potential. Returns a score (0-100) indicating how compelling and clickable the title is. Use this to compare title variations and pick the best-performing option. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_SIMILAR_CHANNELS` | Vidiq similar channels | Find COMPETITORS of a channel — either the user's own channel or a specific named channel. Uses neural semantic search tuned for competitor matching; the user's own authorized channels are automatically excluded from legacy manual-mode results. Use this tool ONLY when someone asks for competitors or similar channels relative to a channel: - "Who are my competitors?" or "Find channels like mine" (the user's own channel — country/language are auto-detected in manual mode) - "Channels similar to [channel]", "Competitors of [channel]", or "Channels like @handle" (a named reference channel) Do NOT use this tool for generic channel discovery by topic, size, growth, or any other criteria ("find tech review channels", "top gaming channels in Brazil", "fastest growing fitness channels") — use vidiq_channel_search for that. Choose exactly one mode: channelId or niche. ADDITIVE CHANNEL ID MODE — when a canonical YouTube channel ID beginning with UC was supplied or already resolved, pass only channelId, plus optional size and sort. Do not copy resolved channel characteristics into this request or add niche/manual filters. Do not call vidiq_channel_search when a canonical ID is already available. A handle or URL must be resolved externally to a canonical channel ID before using this mode. The API derives the source classification and search tuning and excludes the reference channel. LEGACY MANUAL NICHE MODE — Legacy manual niche behavior is unchanged. The niche parameter is required in this mode — always provide a clear topic or content theme. All existing manual inputs remain supported, including minSubscribers, maxSubscribers, avgViews, avgViewsMin, avgViewsMax, country, language, channelType, faceless, and excludeChannelIds. SIMILAR TO A SPECIFIC CHANNEL IN LEGACY MANUAL MODE — when using the existing manual path, do NOT guess the reference channel's characteristics. Supply the same fields as before: - niche: the reference channel's niche + subNiches, comma-separated (e.g. 'YouTube Growth, Monetization & SEO') - country: the reference channel's country - language: the first code from the reference channel's languages - channelType: the reference channel's channelType - faceless: the reference channel's isFaceless value - minSubscribers / maxSubscribers: a band around its subscriberCount, roughly 10% as min and 5x as max, unless the user asks for a specific range - avgViews: the reference channel's avgViews; do not also set avgViewsMin/avgViewsMax unless the user asks for a specific range - excludeChannelIds: the reference channel's channelId Omit sort for normal similarity ranking. When the user asks to rank these competitors by size or recent growth, set sort to subscriberCount, subsGrowth30d, or viewsGrowth30d; all explicit sorts reorder only the requested top similarity results. Results include the metrics used for sorting plus channel type and faceless status. In manual niche mode, country is a ranking preference rather than a strict filter, while language filters the language channels publish in. When omitted, country and language are auto-detected from the user's authorized channel. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_SIMILAR_THUMBNAILS` | Vidiq similar thumbnails | Find long-form YouTube videos whose thumbnails LOOK similar — visual/semantic similarity over the thumbnail images themselves. This tool searches long-form videos only; Shorts are not supported. This is not topic, title, or keyword search (for those use vidiq_outliers or vidiq_youtube_search). Two modes: pass `description` with a textual description of the imagery (e.g. "a shocked creator pointing at a red analytics chart") to find thumbnails matching that description, or pass `videoId` to find thumbnails that look like that video's thumbnail (resolved automatically — no image upload needed). Useful for thumbnail inspiration, checking how common a thumbnail concept is, or finding which visual styles perform well in a niche. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_SIMILAR_VIDEOS` | Vidiq similar videos | Find high-performing YouTube videos similar to a seed video - the video-level counterpart of vidiq_similar_channels. Give it one video ID or URL and it returns videos ranked by combined similarity: textual (title/topic) and visual (thumbnail), fused with each video labeled by which signals matched (`matchedBy`; matching both earns a ranking boost). Use this for topic ideation ('find 50 videos like this outlier'), studying how a proven concept is packaged across channels, or expanding one winning video into a content cluster. Searches vidIQ's high-performing/outlier video index - results skew toward videos that overperform, which is what makes them useful as ideation references. Results are ordered most-similar-first; no numeric similarity score is exposed. Use `minEngagementRate` to filter copycat/re-upload spam around viral seeds. Check `signalsUsed`/`signalsFailed` before interpreting an empty result. For channel-level similarity use vidiq_similar_channels; for thumbnail-only search use vidiq_similar_thumbnails. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_SUBMIT_FEEDBACK` | Vidiq submit feedback | Submit feedback about the vidIQ MCP — feature requests, bug reports, improvement suggestions, survey responses, or general comments. When the user encounters a bug with vidIQ MCP or requests a new vidIQ MCP feature, proactively ask whether they would like you to submit a bug report or feature request to vidIQ. Call this tool when the user explicitly asks to submit, send, record, or report feedback to vidIQ. Comments made while asking for help do not by themselves indicate submission intent. If submission intent is ambiguous, ask whether the user wants the feedback sent to vidIQ and wait for confirmation. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_SUBSCRIBER_INSIGHTS` | Vidiq subscriber insights | Analyze subscriber overlap and best times to post for a YouTube channel you own. Returns the channels most commonly subscribed to by your audience, dated overlap history, and a timezone-adjusted histogram of sampled public YouTube activity with the strongest three-hour windows. The activity signal is not watch history or live online-presence data. Only channels authorized to your account are allowed. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_TREND_CATEGORIES` | Vidiq trend categories | List all available trend category slugs with display names and descriptions. Use this as a reference before filtering outlier videos by trend category. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_TRENDING_VIDEOS` | Vidiq trending videos | Find YouTube videos that are trending right now — gaining views rapidly based on views-per-hour velocity. Use this when someone asks: what's trending, what's hot right now, popular videos this week, or fastest-growing videos. Unlike vidiq_outliers (which measures performance vs channel average), trending measures absolute velocity — high VPH regardless of channel size. Use this tool to discover: - Videos that are trending right now on YouTube - Trending content in specific niches via title search - High-performing videos filtered by views per hour, engagement, or subscriber range For language-specific discovery, pass the user's requested actual video-title language in `videoTitleLanguage`. `channelCountry` only restricts where channels are based; it does not represent audience geography or video language. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_UPDATE_COMPETITORS` | Vidiq update competitors | Follow or unfollow competitor channels for one of the user's own YouTube channels. - youtubeChannelId must be a channel the user has authorized (call vidiq_user_channels to discover). - follow / unfollow are arrays of YouTube channel IDs — they must not overlap; at least one must be non-empty. - Plan-based caps apply. Adding above the cap fails. Returns the resulting tracked-competitors list (channel IDs only). Example arguments: { "youtubeChannelId": "UCowner123", "follow": ["UCcompA"], "unfollow": [] } Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_UPDATE_VIDEO` | Vidiq update video | Update metadata or publishing settings for a YouTube video owned by the user. Supported updates match the vidIQ web app: title, description, complete tag list, privacy status, and scheduled publish time. Omitted fields remain unchanged. An empty description clears the description, and an empty tags array clears all tags. Thumbnail updates use a separate endpoint and are not supported by this tool. Call this write tool only after the user explicitly chooses the exact channel, video, and final values to publish. Do not call it merely to preview, recommend, score, or draft changes. The channel must be directly authorized with owner access (call vidiq_user_channels if unknown), and the current vidIQ OAuth token must include YouTube verification. When the result status is verification_required, show the verification widget and wait for the user to use its controls. Do not retry the video update until the user confirms verification is complete. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_USER_CHANNELS` | Vidiq user channels | Get the list of YouTube channels authorized by the current user. The response includes `authenticatedAs` (the email of the connected vidIQ account). An empty `channels` list usually means the user authorized a different account than they expected — tell them which account they're connected as and suggest reconnecting with the intended one rather than treating it as an error. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_USER_VIDEOS` | Vidiq user videos | List videos from one of the current user's directly authorized YouTube channels through the authenticated vidIQ MCP connection, including public, unlisted, and private videos. Use vidiq_user_channels when the channel ID is unknown. Supports privacy, video-type, title-search, ordering, limit, and cursor filters. Use vidiq_channel_videos for arbitrary public channels. Do not fall back to public results when channel authorization fails. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VIDEO_CHANGE_HISTORY` | Vidiq video change history | Get the observed title and thumbnail change history for one YouTube video. Each change records when a title or thumbnail edit was observed. Thumbnail entries include the original YouTube URL and vidIQ's archived snapshot URL. The response also includes observed thumbnail A/B tests and their variants. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VIDEO_COMMENTS` | Vidiq video comments | Get YouTube comment threads for a video or channel, including replies. Provide exactly one of videoId or channelId. Each returned thread carries the videoId and videoTitle it belongs to, so channel-wide results can be attributed to individual videos. Either field is omitted when YouTube does not report it or the video's metadata is unavailable. Use this tool to: - Understand audience sentiment and reactions to a video - Find common questions or feedback themes in comments - Browse recent comments across an entire channel - Identify the most liked or discussed comments Paging and filtering: maxResult is the upstream page size, and minLikes filters that page by top-level comment likes. A page can therefore come back with fewer threads than maxResult, or with none at all, while more matches still exist. Each page is a separate charged call, so do not sweep to exhaustion by default: fetch another page with the returned nextPageToken (same filters) only while you still need more evidence and the caller's budget allows, and stop as soon as you have enough. A null nextPageToken means the upstream corpus is exhausted and there is nothing left to read. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VIDEO_EARNINGS_ESTIMATE` | Vidiq video earnings estimate | Estimate a single YouTube video's ad-revenue earnings as a low/mid/high range in USD. Give it a video id or URL. It resolves whether the video is long-form or a Short, looks up the channel's category and country, and applies vidIQ's RPM model (category RPM x geo multiplier, with a much lower RPM for Shorts). Use this to answer "how much did/does this video earn?". Important: this is a rough estimate, not exact. It assumes the channel is monetized, uses the channel's country as a proxy for viewer geography, and counts all views as ad-serving. Channels under ~1,000 subscribers are usually not monetized. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VIDEO_STATS` | Vidiq video stats | Get historical statistics for a YouTube video over time, including views, likes, comments, and views per hour (VPH). Use this tool to: - Track how a video's performance changes over time - Compare view velocity (VPH) across different periods - Analyze engagement trends (likes, comments) for a specific video Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VIDEO_TRANSCRIPT` | Vidiq video transcript | Get the full transcript (captions) of a YouTube video. Use this tool to: - Analyze what a video talks about without watching it - Extract key topics, quotes, or timestamps from a video - Compare content across multiple videos by reading their transcripts - Research video content for SEO or content strategy purposes When a language is requested, this tool never silently substitutes captions in another language. Cost: 5 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VIDEO_UPLOAD` | Vidiq video upload | Import an MP4 attachment or public downloadable URL and return a hosted videoUrl plus uploadId. Provide exactly one of file, url, or uploadId. The server transfers and completes the upload; no separate upload or completion step is needed. MP4s must be at most 209715200 bytes with a public HTTPS download URL, Content-Length and MP4 or application/octet-stream content type; redirects are rejected. Local file paths cannot be read. Pass uploadId to this same tool to check waiting/processing uploads or refresh an expired signed URL without transferring the file again. Failed uploads require a new import. Once ready, review videoUrl, then use it in vidiq_generate_video, vidiq_compose, or vidiq_instagram_publish_reel. No credits are charged. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VIDEO_WATCH` | Vidiq video watch | Watch a long-form YouTube video end-to-end and return a structured markdown walkthrough. Use this tool to: - Understand what happens visually in a video (not just what is said) — useful when transcripts miss context - Generate scene-by-scene breakdowns with timestamps for editing or analysis - Answer specific questions about a video by passing a custom `prompt` - Compare visual structure across videos for SEO / hook research This runs asynchronously: it returns an `mcpJobId` immediately. Poll `vidiq_job_poll` with that id until it is "completed" to get the markdown walkthrough in the `analysisText` field. Credits are charged on submit and automatically refunded if the analysis fails. For short-form content, use `vidiq_watch_shortform_content` instead. Note: prefer `vidiq_video_transcript` when you only need spoken words, since it is faster and cheaper. Cost: 25 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VOICEOVER_CLONE` | Vidiq voiceover clone | Clone a voice from an audio sample and save it to the user's voice library. Provide a base64-encoded audio sample (a 60-600s MP3/WAV/M4A clip of a single speaker who has consented to being cloned) and a display name. Each user may keep at most 3 custom voices. Video samples are not accepted — extract the audio first. This runs asynchronously: it returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it is "completed" to get the new voiceId (usable with vidiq_voiceover_generate). Credits are charged on submit and automatically refunded if cloning fails. Cloning is NOT retried automatically: if the poll reports an ambiguous failure, check vidiq_voiceover_list_voices before submitting again — the voice may already exist. Cost: 50 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VOICEOVER_CLONE_START` | Vidiq voiceover clone start | Start cloning the speaker's voice from a YouTube video. Provide a public YouTube URL and a name for the voice. This runs asynchronously: it returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it completes, then use the returned `voiceId`. Credits are charged on submit and automatically refunded if the clone fails. Cost: 1 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_VOICEOVER_GENERATE` | Vidiq voiceover generate | Generate a voiceover MP3 from a script. Provide the script text (max 5000 characters) and a voiceId from vidiq_voiceover_list_voices. This runs asynchronously: it returns an `mcpJobId` immediately. Poll `vidiq_job_poll` with that id until it is "completed" to get the audio duration, character count, and hosted MP3 URL. Credits are charged on submit and automatically refunded if generation fails. Cost: 14 credit(s) per 1000 characters of script (rounded up). |
| `VIDIQ_MCP_VIDIQ_VOICEOVER_LIST_VOICES` | Vidiq voiceover list voices | List the available voiceover voices. Returns each voice's id, name, category, description, and an optional audio preview URL. The user's own cloned/designed voices have isCustom=true and are listed first; prefer them when the user asks for "my voice". Use the returned voiceId with vidiq_voiceover_generate. Cost: 0 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_WATCH_SHORTFORM_CONTENT` | Vidiq watch shortform content | Watch one piece of short-form content from Instagram, TikTok, or YouTube and return a markdown scene-by-scene walkthrough. Pass the full public URL. For YouTube Shorts, a /shorts/, watch, or youtu.be URL is accepted; the content is verified to be short-form. Call this tool in parallel to compare multiple pieces of short-form content. This runs asynchronously: it returns an `mcpJobId` immediately — poll `vidiq_job_poll` with that id until it is "completed" to get the walkthrough. Credits are charged on submit and automatically refunded if the analysis fails. DO NOT USE FOR: - Long-form YouTube videos — use `vidiq_video_watch`. - TikTok short links (vm.tiktok.com or tiktok.com/t/) — paste the full /@user/video/ URL. - Bare platform IDs or Instagram shortcodes — pass a full URL. Cost: 10 credit(s) per call. |
| `VIDIQ_MCP_VIDIQ_YOUTUBE_SEARCH` | Vidiq youtube search | Search all of YouTube for videos, channels, or playlists matching a query, with optional filters (topic, region, publish date, duration, channel). Use this when someone asks to "find videos about X", "search YouTube for Y", "find channels about Z", or wants results for a specific keyword. Unlike vidiq_trending_videos (which returns what's hot right now) and vidiq_outliers (which finds videos over-performing relative to their channel), this is a general keyword search across the whole catalog. It returns raw YouTube search results, NOT keyword metrics — for search volume/competition use keyword research instead. Use this tool to: - Find videos, channels, or playlists by keyword (set 'type') - Narrow results by topic, region, publish-date window, and (for videos) duration, definition (HD), or live/upcoming event type - Search within a single channel by passing 'channelId' - Sort by relevance, recency ('date'), or popularity ('viewCount') Filters marked "Video only" require type='video'. Cost: 5 credit(s) per call. |

## Supported Triggers

None listed.

## Troubleshooting

### 1. Why does Claude not use the Composio connector for vidIQ?

The connector can show as connected, but Claude must use it in each vidIQ conversation.
- Click + at the lower left of the chat, or type /.
- Hover Connectors.
- Turn on Composio.
- Ask Claude to connect to vidIQ again.

### 2. Why does Claude show an MCP server error before vidIQ connects?

Claude can show Couldn't reach the MCP server or Authorization with the MCP server failed when you add the connector for vidIQ.
- Check that the connector URL is https://connect.composio.dev/mcp.
- Connectors run from Anthropic's cloud, so your device network is usually not the problem.
- Add the connector again from Customize > Connectors, then ask Claude to connect vidIQ.
- If it fails again, send the error and the ofid_ reference id to support@composio.dev.

### 3. Why does the vidIQ authorization link not work?

The Composio connector is one server. Your vidIQ account connects separately when Claude asks for it.
- If the browser does not open, or the link expires, ask Claude to retry the vidIQ connection.
- Composio creates a fresh vidIQ authorization link.
- Open that link in your browser and finish the vidIQ sign-in.

### 4. Why do vidIQ actions fail after they worked before?

The vidIQ connection can expire or lose permission.
- Ask Claude to inspect the vidIQ connection.
- If the connection is unhealthy, disconnect it when Claude prompts you.
- Reconnect the vidIQ account and retry the action.
- If Claude shows a permission prompt, approve it before Claude changes data in vidIQ.
- If the action still fails with a permission error, check that the connected account has that permission in vidIQ itself.

### 5. How do I switch to a different vidIQ account?

Claude can manage the vidIQ connection for you.
- Ask Claude to disconnect or delete the current vidIQ account.
- Ask Claude to connect vidIQ again.
- Open the new Composio authorization link for vidIQ.
- Sign in with the other vidIQ account in the browser.
- After the account connects, ask Claude to retry the vidIQ task.

### 6. Why is my vidIQ connection missing in Claude Desktop or on a Team plan?

The connector belongs to your Claude account, so your vidIQ connection works in Claude Web, Desktop, and Cowork.
- In Claude Desktop, open Customize > Connectors.
- Next to Composio, click ⋮ and click Clear cache.
- If vidIQ tools still do not appear, click ⋮, disconnect, remove the connector, and add it again.
- On Team or Enterprise, an Owner or Primary Owner must enable the connector before you can connect vidIQ.

## Creating MCP Server - Stand-alone vs Composio SDK

The vidIQ MCP server connects Claude Web, Desktop, and Cowork to your vidIQ account through Composio. Once connected, Claude can use the available vidIQ tools and triggers to complete tasks on your behalf.

## Complete Code

None listed.

## How to build vidIQ MCP Agent with another framework

- [ChatGPT](https://composio.dev/toolkits/vidiq_mcp/framework/chatgpt)
- [Hermes](https://composio.dev/toolkits/vidiq_mcp/framework/hermes-agent)
- [Atomic Agent](https://composio.dev/toolkits/vidiq_mcp/framework/atomic-agent)

## Related Toolkits

- [Reddit](https://composio.dev/toolkits/reddit) - Reddit is a social news platform with thriving user-driven communities (subreddits). It's the go-to place for discussion, content sharing, and viral marketing.
- [Facebook](https://composio.dev/toolkits/facebook) - Facebook is a social media and advertising platform for businesses and creators. It helps you connect, share, and manage content across your public Facebook Pages.
- [Linkedin](https://composio.dev/toolkits/linkedin) - LinkedIn is a professional networking platform for connecting, sharing content, and engaging with business opportunities. It's the go-to place for building your professional brand and unlocking new career connections.
- [Active campaign](https://composio.dev/toolkits/active_campaign) - ActiveCampaign is a marketing automation and CRM platform for managing email campaigns, sales pipelines, and customer segmentation. It helps businesses engage customers and drive growth through smart automation and targeted outreach.
- [ActiveTrail](https://composio.dev/toolkits/active_trail) - ActiveTrail is a user-friendly email marketing and automation platform. It helps you reach subscribers and automate campaigns with ease.
- [Adobe Marketing Agent MCP](https://composio.dev/toolkits/adobe_marketing_agent_mcp) - Adobe Marketing Agent MCP is Adobe's hosted MCP service that exposes marketing context, preferences, and agent capabilities. Use it to provide agents with campaign, audience, and analytics context via a managed integration.
- [Ahrefs](https://composio.dev/toolkits/ahrefs) - Ahrefs is an SEO and marketing platform for site audits, keyword research, and competitor insights. It helps you improve search rankings and drive organic traffic.
- [AimTell](https://composio.dev/toolkits/aimtell) - AimTell is a web push notification platform for managing websites, subscribers, campaigns, segments, and delivery analytics. Use it to send targeted browser notifications and measure engagement across your web push campaigns.
- [Amcards](https://composio.dev/toolkits/amcards) - AMCards lets you create and mail personalized greeting cards online. Build stronger customer relationships with easy, automated card campaigns.
- [AWeber](https://composio.dev/toolkits/aweber) - AWeber is an email marketing platform for creating campaigns, lists, and landing pages. It helps businesses automate email outreach and measure subscriber engagement.
- [Beamer](https://composio.dev/toolkits/beamer) - Beamer is a news and changelog platform for in-app announcements and feature updates. It helps companies boost user engagement by sharing news where users are most active.
- [Beehiiv](https://composio.dev/toolkits/beehiiv) - Beehiiv is a newsletter platform for creating and managing publications and subscribers. It helps grow audience engagement and monetize your mailing list.
- [Benchmark email](https://composio.dev/toolkits/benchmark_email) - Benchmark Email is a platform for creating, sending, and tracking email campaigns. It's built to help you engage audiences and analyze results—all in one place.
- [Bigmailer](https://composio.dev/toolkits/bigmailer) - BigMailer is an email marketing platform for managing multiple brands with white-labeling and automation. It helps teams streamline campaigns and simplify integration with Amazon SES.
- [Bitly](https://composio.dev/toolkits/bitly) - Bitly is a link management platform for shortening, customizing, sharing, and tracking links and QR codes. It helps teams create branded links and measure engagement across campaigns.
- [BlueFox Email](https://composio.dev/toolkits/bluefox_email) - BlueFox Email is an email API for managing contacts, subscriber lists, and sending transactional and triggered messages. Use it to reliably send transactional and triggered emails and manage subscribers at scale.
- [Brandfetch](https://composio.dev/toolkits/brandfetch) - Brandfetch is an API that delivers company logos, colors, and visual branding assets. It helps marketers and developers keep brand visuals consistent everywhere.
- [Braze](https://composio.dev/toolkits/braze) - Braze is a customer engagement platform for managing user data, messaging, campaigns, and analytics. Use it to deliver targeted, multi-channel messaging and analyze campaign performance.
- [Brevo](https://composio.dev/toolkits/brevo) - Brevo is an all-in-one email and SMS marketing platform for transactional messaging, automation, and CRM. It helps businesses engage customers and streamline communications through powerful campaign tools.
- [Buffer](https://composio.dev/toolkits/buffer) - Buffer is a social media management platform for planning, creating, scheduling, and publishing posts across connected channels. It helps teams keep content organized and publish consistently without jumping between social apps.

## Frequently Asked Questions

### What are the differences in Tool Router MCP and vidIQ MCP?

With a standalone vidIQ MCP server, the agents and LLMs can only access a fixed set of vidIQ tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from vidIQ and many other apps based on the task at hand, all through a single MCP endpoint.

### Can I use Tool Router MCP with Claude Cowork?

Yes, you can. Claude Cowork fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right vidIQ tools.

### Can I manage the permissions and scopes for vidIQ while using Tool Router?

Yes, absolutely. You can configure which vidIQ scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

### How safe is my data with Composio Tool Router?

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your vidIQ data and credentials are handled as safely as possible.

---
[See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)