TubeMagic MCP

Get what TubeMagic Agent costs per reply, the user's credits, the connected YouTube channels the Agent can focus on, and example requests.

No parameters

Ask TubeMagic Agent to do YouTube work end to end: research outliers and formats, analyse the user's channels, write scripts, generate thumbnails, write titles, descriptions, tags and full upload packages, generate video ideas and community posts, research keywords, explore niches, suggest channel names, get video transcripts, and save ideas. It runs TubeMagic's tools itself and returns its reply, each step it ran, and results merged by type (scripts, thumbnails, videos with outlier scores, formats, ideas, titles) with links. Leave chatId empty to start a new chat, or pass one to continue it. To let the Agent use apps the user connected (like Vid.AI for making videos), pass them in connectors; get_agent_options lists them. Paste YouTube video, channel or playlist links and web page links straight into the message; the Agent opens them, and can read many videos' transcripts to compare them. Attach images, PDFs or text files with attachments, as public links, plain text or base64. Each reply costs 10 credits plus whatever its tools use, and needs a paid TubeMagic plan; failed replies are refunded. When awaitingApproval is returned, the Agent paused before a delete, a credit-spending action or a model choice: ask the user, then call answer_agent_approval.

• messagerequired

  string

  What the Agent should do

• chatId

  string

  Agent chat to continue. Leave empty to start a new chat

• channelId

  string

  Optional connected channel ID (from get_agent_options) for the Agent to focus on

• attachments

  object[]

  Up to 5 files for the Agent to read: Images (PNG, JPG, WebP, GIF), PDF, TXT, MD, CSV, JSON, SRT and VTT. Give each file as exactly one of url (public link), text (contents of a text file) or base64 (an image or PDF). The Agent sees images and reads the text of PDFs and text files. For YouTube or web page links, put them in the message instead

• connectors

  string[]

  Connected apps the Agent may use in this message, by connectorId or name from get_agent_options (for example ["Vid.AI"]). Leave empty to use none

Approve or skip the actions the Agent paused on (awaitingApproval from send_agent_message or get_agent_chat), then let it continue and return its reply. Actions left out are skipped. For actions with modelOptions, pass the model the user picked (defaults to defaultModel). Continuing costs 10 credits plus what the approved actions use.

• chatIdrequired

  string

  The Agent chat id

• messageIdrequired

  string

  awaitingApproval.messageId

• decisionsrequired

  object[]

  One decision per action

• channelId

  string

  Optional connected channel ID (from get_agent_options) for the Agent to focus on

Get the Agent's reply to the last message of a chat when it has none yet, for example after a failed reply. Costs 10 credits plus what its tools use.

• chatIdrequired

  string

  The Agent chat id

• channelId

  string

  Optional connected channel ID (from get_agent_options) for the Agent to focus on

• connectors

  string[]

  Connected apps the Agent may use in this message, by connectorId or name from get_agent_options (for example ["Vid.AI"]). Leave empty to use none

List the user's TubeMagic Agent chats (including older TubeMagic Chat conversations), most recently updated first. Search matches titles and messages.

• search

  string

  Text to match in chat titles and messages

• page

  integer · default 1

• limit

  integer · default 10

  Chats per page, up to 50

Get an Agent chat and its messages, oldest first, a page at a time, with the steps and result cards of each Agent reply and any approval it is waiting on. Use pagination.totalPages to jump to the latest messages.

• chatIdrequired

  string

  The Agent chat id

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Messages per page, up to 50

Rename a TubeMagic Agent chat.

• chatIdrequired

  string

  The Agent chat id

• titlerequired

  string

  The new chat title

Delete a TubeMagic Agent chat and its messages. Confirm with the user first.

• chatIdrequired

  string

  The Agent chat id

List the files attached to TubeMagic Agent chats (images, PDFs and text files), newest first, with their chat, size, pages and word count. Pass chatId for one chat. Use get_agent_file to read one.

• chatId

  string

  Only files from this Agent chat

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Files per page, up to 50

Get a file attached to a TubeMagic Agent chat: its details, a download link that works for 60 minutes, and for PDFs and text files the text the Agent read from it.

• fileIdrequired

  string

  The file id

• maxChars

  integer · default 20000

  Characters of extracted text to return. 0 for none

Video Research: search YouTube videos with views, views per hour, engagement rate, and Outlier Score (views compared to the channel average; above 1x beat the average). Filter by type, duration, upload date, features, region, language, minimum Outlier Score, and channel subscriber range. Use nextPageToken for more results. Without a query, or when nothing matches, it returns videos from the user's saved videos and tracked channels instead (fromYourLibrary is true). Needs a paid TubeMagic plan. Uses the shared Video Research limit of 500 operations per 24 hours.

• query

  string

  What to search for, at least 2 characters

• type

  enum

  Only regular videos or only Shorts

• duration

  enum

  short = under 4 minutes, medium = 4 to 20 minutes, long = over 20 minutes

• sortBy

  enum

  Sort results (default relevance)

• uploadDate

  enum

  Only videos uploaded within this period

  hourtodayweekmonthyear
• features

  enum[]

  Only videos with all of these features

  HDsubtitlesCCommons3DLivePurchased4K360LocationHDRVR180
• region

  string

  Two-letter country code, like US or IN

• language

  string

  Language code, like en or hi

• localOnly

  boolean

  Prefer results local to the region

• minOutlierScore

  number

  Only videos with at least this Outlier Score, like 3 for 3x the channel average

• minSubscribers

  integer

  Only videos from channels with at least this many subscribers

• maxSubscribers

  integer

  Only videos from channels with at most this many subscribers

• pageToken

  string

  nextPageToken from the previous results, with the same query and filters

Get YouTube search suggestions for a partial query, to find popular search phrases. Uses the shared Video Research limit of 500 operations per 24 hours.

• queryrequired

  string

  The partial search text

• limit

  integer · default 8

  Suggestions to return, up to 12

Suggest new videos related to the videos saved in one of the user's Video Research folders, excluding ones already in it. Seeds are picked at random from the folder, so each call can return different videos. Uses the shared Video Research limit of 500 operations per 24 hours.

• folderIdrequired

  string

  The saved-videos folder id. Use list_video_folders to find it

• type

  enum

  Only regular videos or only Shorts

• duration

  enum

  short = under 4 minutes, medium = 4 to 20 minutes, long = over 20 minutes

• sortBy

  enum

  Sort results (default relevance)

• uploadDate

  enum

  Only videos uploaded within this period

  hourtodayweekmonthyear
• features

  enum[]

  Only videos with all of these features

  HDsubtitlesCCommons3DLivePurchased4K360LocationHDRVR180
• region

  string

  Two-letter country code, like US or IN

• language

  string

  Language code, like en or hi

• localOnly

  boolean

  Prefer results local to the region

• limit

  integer · default 12

  Videos to return, up to 30

Search YouTube channels by name or handle, to add to a tracking database. Pass trackingId to mark channels already in that database. Uses the shared Video Research limit of 500 operations per 24 hours.

• queryrequired

  string

  Channel name or handle

• trackingId

  string

  Optional tracking database id

• limit

  integer · default 12

  Channels to return, up to 12

List the user's saved Video Research videos with their note, tags, folders, views, engagement, and Outlier Score. Search matches titles, channels, notes, tags, and folder names. Filter by folder, tags, likes, Outlier Score, subscribers, duration, and publish date. Uses the shared Video Research limit of 500 operations per 24 hours.

• search

  string

  Text to search for

• folderId

  string

  Only videos in this folder

• tagIds

  string[]

  Only videos with any of these tags

• minLikes

  number

  Minimum likes

• maxLikes

  number

  Maximum likes

• minOutlierScore

  number

  Minimum Outlier Score, like 2 for 2x the channel average

• maxOutlierScore

  number

  Maximum Outlier Score

• minSubscribers

  number

  Minimum channel subscribers

• maxSubscribers

  number

  Maximum channel subscribers

• minDurationSeconds

  number

  Minimum duration in seconds

• maxDurationSeconds

  number

  Maximum duration in seconds

• durationBucket

  enum · default "any"

  short = under 4 minutes, medium = 4 to 20, long = over 20

  anyshortmediumlong
• publishedRange

  enum · default "any"

  Only videos published within this period

  anyhourtodayweekmonthyear
• sortBy

  enum · default "updatedAt"

  updatedAtlikesoutliersubscribersdurationpublishedviews
• sortDirection

  enum · default "desc"

  ascdesc
• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Results per page, up to 50

Save a YouTube video to Video Research, or update a saved one, with an optional note, folders, and tags. By default folders and tags are added to the existing ones and the note is kept unless given; set replace to true to overwrite them all. Uses the shared Video Research limit of 500 operations per 24 hours.

• videorequired

  string

  A YouTube video ID or URL

• note

  string | null

  A note about the video; null clears it

• folderIds

  string[]

  Folders to put the video in

• tagIds

  string[]

  Tags to add to the video

• replace

  boolean · default false

  Replace the note, folders, and tags instead of adding to them

Remove a video from the user's saved Video Research videos. Uses the shared Video Research limit of 500 operations per 24 hours.

• videorequired

  string

  A YouTube video ID or URL

List the user's Video Research folders for saved videos. Search matches folder names and keywords. Uses the shared Video Research limit of 500 operations per 24 hours.

• search

  string

  Text to match in folder names

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Results per page, up to 50

Create a folder for saved Video Research videos. Give a video to seed the folder with its channel's keywords. Uses the shared Video Research limit of 500 operations per 24 hours.

• namerequired

  string

  Folder name

• video

  string

  A YouTube video ID or URL

List the user's Video Research tags for saved videos. Uses the shared Video Research limit of 500 operations per 24 hours.

• search

  string

  Text to match in tag names

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Results per page, up to 50

Create a Video Research tag for saved videos. If a tag with the same name exists, it is returned instead. Uses the shared Video Research limit of 500 operations per 24 hours.

• namerequired

  string

  Tag name

List the user's Video Research tracking databases: named groups of YouTube channels whose videos TubeMagic tracks. Pinned ones come first. Uses the shared Video Research limit of 500 operations per 24 hours.

• search

  string

  Text to match in database names

• isPinned

  boolean

  Only pinned or only unpinned databases

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Results per page, up to 50

Create a Video Research tracking database. If one with the same name exists (even a deleted one), it is reused. Uses the shared Video Research limit of 500 operations per 24 hours.

• namerequired

  string

  Database name

• isPinned

  boolean · default false

  Pin it to the top

Rename a tracking database or pin/unpin it. Uses the shared Video Research limit of 500 operations per 24 hours.

• trackingIdrequired

  string

  The tracking database id. Use list_tracking_databases to find it

• name

  string

  New name

• isPinned

  boolean

  Pin or unpin it

Delete a tracking database and hide its video formats. Confirm with the user first. Uses the shared Video Research limit of 500 operations per 24 hours.

• trackingIdrequired

  string

  The tracking database id. Use list_tracking_databases to find it

List the channels in a tracking database with subscribers, videos, average and total views, and durations, with filters and sorting. Uses the shared Video Research limit of 500 operations per 24 hours.

• trackingIdrequired

  string

  The tracking database id. Use list_tracking_databases to find it

• search

  string

  Text to match in channel name, handle, or id

• minSubscribers

  number

  Minimum subscribers

• maxSubscribers

  number

  Maximum subscribers

• minVideos

  number

  Minimum videos

• maxVideos

  number

  Maximum videos

• minAvgViews

  number

  Minimum average views

• maxAvgViews

  number

  Maximum average views

• minTotalViews

  number

  Minimum total views

• maxTotalViews

  number

  Maximum total views

• minAvgDurationSeconds

  number

  Minimum average video duration in seconds

• maxAvgDurationSeconds

  number

  Maximum average video duration in seconds

• durationBucket

  enum · default "any"

  By average video duration: short = under 4 minutes, medium = 4 to 20, long = over 20

  anyshortmediumlong
• sortBy

  enum · default "videos"

  namesubscribersvideosavgViewstotalViewsavgDurationtotalDuration
• sortDirection

  enum · default "desc"

  ascdesc
• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Results per page, up to 50

Add a YouTube channel to a tracking database. TubeMagic first syncs all of its videos, which can take a minute for big channels. Channels with more than 2000 videos are not supported. Uses the shared Video Research limit of 500 operations per 24 hours.

• trackingIdrequired

  string

  The tracking database id. Use list_tracking_databases to find it

• channelrequired

  string

  Channel ID (UC...), handle like @mkbhd, channel URL, or name

Remove a channel from a tracking database. Its videos stop appearing in the database. Uses the shared Video Research limit of 500 operations per 24 hours.

• trackingIdrequired

  string

  The tracking database id. Use list_tracking_databases to find it

• channelIdrequired

  string

  The channel ID (UC...) as listed by list_tracked_channels

List videos from all channels in a tracking database with views, engagement, and Outlier Score, plus whether each is saved. Filter by views, Outlier Score, duration, and publish date; sort and page through results. Uses the shared Video Research limit of 500 operations per 24 hours.

• trackingIdrequired

  string

  The tracking database id. Use list_tracking_databases to find it

• search

  string

  Text to match in titles, descriptions, and channel names

• minViews

  number

  Minimum views

• maxViews

  number

  Maximum views

• minOutlierScore

  number

  Minimum Outlier Score, like 2 for 2x the channel average

• maxOutlierScore

  number

  Maximum Outlier Score

• minDurationSeconds

  number

  Minimum duration in seconds

• maxDurationSeconds

  number

  Maximum duration in seconds

• durationBucket

  enum · default "any"

  short = under 4 minutes, medium = 4 to 20, long = over 20

  anyshortmediumlong
• publishedRange

  enum · default "any"

  Only videos published within this period

  anyhourtodayweekmonthyear
• detailsMode

  enum · default "any"

  full = only videos with description, thumbnail, and duration

  anyfull
• sortBy

  enum · default "published"

  updatedAtviewspublisheddurationoutlierlikes
• sortDirection

  enum · default "desc"

  ascdesc
• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Results per page, up to 50

Suggest new YouTube channels similar to the ones in a tracking database, found from videos related to its channels. Results are cached for 30 minutes unless refresh is true. Uses the shared Video Research limit of 500 operations per 24 hours.

• trackingIdrequired

  string

  The tracking database id. Use list_tracking_databases to find it

• limit

  integer · default 10

  Suggestions to return, up to 10

• refresh

  boolean · default false

  Ignore cached suggestions

List generated video formats: reusable title templates like "I Tried [THING] for [TIME]" with their variables, why they work, example titles, and the source video stats. Formats belong to a tracking database or to the user's general feed. Up to 100 formats, a page at a time. Uses the shared Video Research limit of 500 operations per 24 hours.

• trackingId

  string

  Optional tracking database id. Without it, formats come from the user's general search feed

• search

  string

  Text to match in formats, titles, channels, and notes

• sortBy

  enum · default "updatedAt"

  Sort by: updatedAt = Recently updated, outlierScore = Outlier score, views = Video views, subscribers = Channel subscribers, averageViews = Average channel views, publishedAt = Video publish date, channelName = Channel name

• sortDirection

  enum · default "desc"

  ascdesc
• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Results per page, up to 50

Save the user's notes on a video format. Notes are kept per tracking database or general feed. Uses the shared Video Research limit of 500 operations per 24 hours.

• formatIdrequired

  string

  The format id from list_video_formats

• notesrequired

  string | null

  The notes, up to 2000 characters; null clears them

• trackingId

  string

  Optional tracking database id. Without it, formats come from the user's general search feed

List the channels that can be picked for advanced format generation, a page at a time: the channels in a tracking database, or a sample of up to 50 channels from the user's general search feed (returned as one page). Uses the shared Video Research limit of 500 operations per 24 hours.

• trackingId

  string

  Optional tracking database id. Without it, formats come from the user's general search feed

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Results per page, up to 50

Generate video formats (reusable title templates) from high-performing videos, for a tracking database or the user's general search feed. Default mode picks 10 source videos automatically and reserves 10 credits. Advanced mode: pass channels with how many formats each (up to 50 in total); use list_video_format_channels to pick them. Charges 1 credit per format actually saved, refunds the rest, and refunds everything if it fails. Needs a paid TubeMagic plan.

• trackingId

  string

  Optional tracking database id. Without it, formats come from the user's general search feed

• channels

  object[]

  Advanced mode: the channels to use. Leave empty for default mode

Get any public YouTube video from its link or ID: title, description, channel, views, likes, duration, publish date, tags, category, caption languages and its Outlier Score (views ÷ the median views of its channel's latest uploads). Use it when the user pastes a video link. For what the video says, use get_video_transcripts. Uses the shared Video Research limit of 500 operations per 24 hours.

• videorequired

  string

  A YouTube video link (watch, youtu.be, shorts, live) or an 11-character video ID

Look up any YouTube channel from a link, @handle, channel ID or one of its video links: name, handle, subscribers, video count, description, and its 5 latest videos with their Outlier Scores. Use it when the user pastes a channel link. To go through its videos use list_channel_videos, and for what it says in them use get_channel_transcripts. Uses the shared Video Research limit of 500 operations per 24 hours.

• channelrequired

  string

  The channel: a channel link (youtube.com/@handle, /channel/UC…, /c/name), an @handle, a channel ID, or a link to any of its videos

List any YouTube channel's long-form videos, Shorts or past live streams, newest, most popular or oldest first, with views, duration, publish time and an Outlier Score (views ÷ the median views of the channel's latest uploads; above 1x beat its usual video). Up to 200 per call; use nextPageToken for more. Use the video IDs with get_video_transcripts, or use get_channel_transcripts to list and read them in one step. Uses the shared Video Research limit of 500 operations per 24 hours.

• channel

  string

  The channel (a link, @handle, channel ID or one of its video links). Not needed with pageToken

• type

  enum · default "videos"

  videos = long-form uploads, shorts = Shorts, live = past live streams

• sort

  enum · default "newest"

  newest first, most popular (by views) first, or oldest first

• limit

  integer · default 30

  Videos to return, up to 200

• pageToken

  string

  nextPageToken from the previous call, to continue the list

List the videos in any public YouTube playlist, in playlist order, with views, duration, channel and an Outlier Score against each video's own channel. Up to 200 per call; use nextPageToken for more. Use it when the user pastes a playlist link, then get_video_transcripts for what the videos say. Uses the shared Video Research limit of 500 operations per 24 hours.

• playlist

  string

  A YouTube playlist link (with list=…) or playlist ID. Not needed with pageToken

• limit

  integer · default 50

  Videos to return, up to 200

• pageToken

  string

  nextPageToken from the previous call, to continue the list

Get what is said in one or more YouTube videos from their captions: the full transcript, only the intro or outro, or a time range, optionally with [m:ss] timestamps. Use it to analyse what videos say, how they hook viewers, their structure, calls to action, or to compare many videos. For a whole channel use get_channel_transcripts instead. Videos without captions come back with status no_captions. Up to 50 videos per call and about 80,000 characters in total; every 10 videos count as one Video Research operation.

• videosrequired

  string[]

  Video links or IDs, up to 50

• section

  enum · default "full"

  full = whole transcript, intro = the first `seconds`, outro = the last `seconds`, range = from startSeconds to endSeconds. Use intro or outro to compare openings or endings across many videos

• seconds

  integer · default 60

  For intro and outro: how many seconds to take, like 30 for a hook or 60 for an intro

• startSeconds

  number

  For range: where to start, in seconds

• endSeconds

  number

  For range: where to stop, in seconds. Leave empty for the end of the video

• language

  string · default "en"

  Preferred caption language, like en or es. Falls back to the video's own language

• includeTimestamps

  boolean · default false

  Put [m:ss] timestamps before each caption line

• maxCharsPerVideo

  integer · default 12000

  Cut each transcript after this many characters

Go through a YouTube channel's videos and get what is said in each, in one call: lists the channel's latest, most popular or oldest videos (or Shorts), then returns each one's transcript, intro, outro or time range. Use it for questions across a channel's videos, like the common themes of their intros (section intro, seconds 30 to 90), how they end videos and ask for subscribers (section outro), recurring topics, phrases or structure (section full). Up to 50 videos per call. Up to 50 videos per call and about 80,000 characters in total; every 10 videos count as one Video Research operation.

• channelrequired

  string

  The channel: a channel link (youtube.com/@handle, /channel/UC…, /c/name), an @handle, a channel ID, or a link to any of its videos

• type

  enum · default "videos"

  videos = long-form uploads, shorts = Shorts, live = past live streams

• sort

  enum · default "newest"

  newest first, most popular (by views) first, or oldest first

• limit

  integer · default 20

  How many of the channel's videos to read, up to 50

• section

  enum · default "full"

  full = whole transcript, intro = the first `seconds`, outro = the last `seconds`, range = from startSeconds to endSeconds. Use intro or outro to compare openings or endings across many videos

• seconds

  integer · default 60

  For intro and outro: how many seconds to take, like 30 for a hook or 60 for an intro

• startSeconds

  number

  For range: where to start, in seconds

• endSeconds

  number

  For range: where to stop, in seconds. Leave empty for the end of the video

• language

  string · default "en"

  Preferred caption language, like en or es. Falls back to the video's own language

• includeTimestamps

  boolean · default false

  Put [m:ss] timestamps before each caption line

• maxCharsPerVideo

  integer · default 12000

  Cut each transcript after this many characters

Read the text of a public web page or online PDF from its link: title, description and the main text, with headings and lists kept. Use it when the user pastes an article, blog post, product page, news story or document link. For YouTube links use the YouTube tools instead. Does not count toward the Video Research limit.

• urlrequired

  string

  The page link

• maxChars

  integer · default 20000

  Cut the text after this many characters, up to 60000

List the Script Writer frameworks, script lengths, reference limits, and exact credit costs for a given length and number of references, plus free scripts left today.

• words

  integer · default 1000

  Script length to price

• referenceCount

  integer · default 0

  Number of references to price

Write a full YouTube video script from a topic or brief, using viral scriptwriting frameworks, at a chosen length. Optionally give up to 3 references (YouTube videos up to 30 minutes with captions, or PDF URLs) for the script to draw on without copying. The script is saved to My Scripts and its scriptId can be used to edit it. Long scripts take a minute or two. Needs a paid TubeMagic plan; free models allow 100 scripts per 24 hours, premium models spend credits (see get_script_writer_options).

• topicrequired

  string

  What the video is about: a topic, brief, or outline, at least 5 words

• words

  integer · default 1000

  Script length in words, one of 100, 150, 200, 250, 300, 500, 750, 1000, 1250, 1500, 1750, 2000, 2250, 2500, 2750, 3000. Up to 300 is a Short

• frameworks

  enum[] · default all

  Scriptwriting frameworks to apply. Defaults to all of them

  Viral Hook DatabaseIntro FrameworksValue Loop StructureStrategic OrderingTension and PacingEmotional WavesPayoff StructuringAdvanced PsychologyOutro StrategyAlgorithm Optimization
• references

  object[] · default []

  Up to 3 references: youtube video URLs or pdf URLs

• model

  enum · default "anthropic/claude-sonnet-5.5"

  AI model to use. Defaults to anthropic/claude-sonnet-5.5 (Sonnet 5.5). anthropic/claude-sonnet-5.5 = Sonnet 5.5 (free, 100 per 24 hours) google/gemini-3-flash-preview = Gemini 3 Flash (free, 100 per 24 hours) anthropic/claude-opus-5.5 = Opus 5.5 (premium, 20 credits for 1000 words without references; more for longer scripts and references) anthropic/claude-fable-5.2 = Fable 5.2 (premium, 40 credits for 1000 words without references; more for longer scripts and references) anthropic/claude-fable-5.1 = Fable 5.1 (premium, 40 credits for 1000 words without references; more for longer scripts and references) openai/gpt-6-astra = GPT-6 Astra (premium, 40 credits for 1000 words without references; more for longer scripts and references)

List the user's saved scripts (My Scripts), newest first, with a preview of each.

• page

  integer · default 1

• limit

  integer · default 20

  Scripts per page, up to 50

Get a saved script in full, with its topic, length, frameworks, model, references, and paragraphs numbered for rewrite_script_paragraph.

• scriptIdrequired

  string

  The script id from write_script or list_my_scripts

Replace the text of a saved script, for example after the user edits it. Paragraphs are separated by blank lines.

• scriptIdrequired

  string

  The script id from write_script or list_my_scripts

• scriptrequired

  string

  The full new script text

Delete a script from My Scripts. Confirm with the user first.

• scriptIdrequired

  string

  The script id from write_script or list_my_scripts

Write alternative opening hooks (first lines) for a saved script, each using a different angle. Use replace_script_hook to swap one in. No credits; needs a paid TubeMagic plan and is blocked once the free daily script limit is reached.

• scriptIdrequired

  string

  The script id from write_script or list_my_scripts

Replace a saved script's opening hook (its first paragraph) with new text, such as one from generate_script_hooks.

• scriptIdrequired

  string

  The script id from write_script or list_my_scripts

• hookrequired

  string

  The new opening hook

Rewrite one paragraph of a saved script following an instruction (like "make it funnier" or "add a statistic"), keeping its length and the script's tone, and save it. Get paragraph numbers from get_script. No credits; needs a paid TubeMagic plan.

• scriptIdrequired

  string

  The script id from write_script or list_my_scripts

• paragraphNumberrequired

  integer

  The paragraph to rewrite, starting at 1

• instructionrequired

  string

  How to rewrite it

List the thumbnail formats, the credit cost per thumbnail, the user's credits, the connected YouTube channels that can be used as a style reference, and the face image limits.

No parameters

List the user's thumbnail projects, most recently updated first, with the latest thumbnail of each. Search matches project names.

• search

  string

  Text to match in project names

• page

  integer · default 1

• limit

  integer · default 12

  Projects per page, up to 50

Get a thumbnail project and its thumbnails, oldest first, a page at a time, including image URLs and the prompt used for each. latestImageId is always the newest thumbnail.

• projectIdrequired

  string

  The thumbnail project id

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Thumbnails per page, up to 50

Create a new thumbnail project and generate its first YouTube thumbnail from an idea. Optionally use a YouTube video for context, a connected channel's latest thumbnails as the style reference, and a face image URL so the person in it appears in the thumbnail. Use edit_thumbnail for changes after that. Takes up to a couple of minutes. Costs 20 credits per thumbnail (refunded if it fails) and needs a paid TubeMagic plan.

• promptrequired

  string

  The thumbnail idea: subject, text, mood, and anything it must show

• format

  enum · default "youtube-video"

  Thumbnail format: youtube-video = YouTube video (16:9), youtube-shorts = YouTube Shorts (9:16)

• youtubeVideoUrl

  string

  Optional YouTube video URL. Its title, description, and transcript are used to make the thumbnail fit the video

• channelId

  string

  Optional connected channel ID (from get_thumbnail_generator_options) whose latest thumbnails set the style

• faceImageUrl

  string

  Optional public URL of a face photo (image/jpeg, image/png, image/webp, up to 5 MB) of the person to feature

Generate a new version of a thumbnail in a project by describing the change, like "make the text bigger" or "use a red background". Edits the latest thumbnail in the project unless imageId is given, keeps everything else, and adds the result to the project. Costs 20 credits (refunded if it fails) and needs a paid TubeMagic plan.

• projectIdrequired

  string

  The thumbnail project id

• instructionrequired

  string

  The change to make

• imageId

  string

  The thumbnail to edit (from get_thumbnail_project). Defaults to the latest one

• format

  enum

  Thumbnail format: youtube-video = YouTube video (16:9), youtube-shorts = YouTube Shorts (9:16). Defaults to the edited thumbnail's format

• youtubeVideoUrl

  string

  Optional YouTube video URL. Its title, description, and transcript are used to make the thumbnail fit the video

Rename a thumbnail project.

• projectIdrequired

  string

  The thumbnail project id

• titlerequired

  string

  The new project name

Delete a thumbnail project and all its thumbnails. Confirm with the user first.

• projectIdrequired

  string

  The thumbnail project id

List the user's Ideas Manager channels (boards that hold video ideas), with how many active ideas each has. The Daily Ideas channel (isDailyIdeas) holds ideas saved from the Today page and does not count toward the limit of 10 channels.

No parameters

Create an Ideas Manager channel to collect video ideas in. Up to 10 channels.

• namerequired

  string

  The channel name

Rename an Ideas Manager channel.

• channelIdrequired

  string

  The idea channel ID from list_idea_channels

• namerequired

  string

  The new channel name

List the ideas in an Ideas Manager channel in board order, filtered like its tabs: active, completed, or archived. Each idea has its progress (scripted, recorded, edited), scheduled date, and thumbnail.

• channelIdrequired

  string

  The idea channel ID from list_idea_channels

• status

  enum · default "active"

  active, completed, archived, or all

• search

  string

  Text to match in idea titles and descriptions

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Ideas per page, up to 50

Add a video idea to the end of an Ideas Manager channel, for example one from get_today_briefing or TubeMagic Agent.

• channelIdrequired

  string

  The idea channel ID from list_idea_channels

• titlerequired

  string

  The idea title

• description

  string

  Notes about the idea

• thumbnailUrl

  string

  Optional image URL to show as the idea thumbnail

• scheduledDate

  string

  Optional date to make the video, like 2026-10-15

Add a YouTube video to an Ideas Manager channel as an idea, with its title, thumbnail, and views, to use as inspiration.

• channelIdrequired

  string

  The idea channel ID from list_idea_channels

• videoUrlrequired

  string

  A YouTube video or Shorts URL

Update an idea: title, description, scheduled date, thumbnail URL, progress (scripted, recorded, edited), completed, or archived. Only the fields given change.

• channelIdrequired

  string

  The idea channel ID from list_idea_channels

• ideaIdrequired

  string

  The idea ID from list_ideas

• title

  string

• description

  string

• scheduledDate

  string | null

  A date like 2026-10-15, or null to clear it

• thumbnailUrl

  string | null

  Image URL, or null to remove the thumbnail

• progress

  enum[]

  The steps done so far, from: SCRIPTED, RECORDED, EDITED

• completed

  boolean

  Mark the idea completed or active again

• archived

  boolean

  Archive or un-archive the idea

Change the order of ideas on an Ideas Manager channel board. The ideas given move to the top in that order; the rest keep their order after them.

• channelIdrequired

  string

  The idea channel ID from list_idea_channels

• ideaIdsrequired

  string[]

  Idea IDs in the order they should appear

Upload an image from a public URL (image/jpeg, image/png, image/webp, up to 10 MB) as an idea's thumbnail, hosted by TubeMagic. Needs the Premium plan, like the website.

• channelIdrequired

  string

  The idea channel ID from list_idea_channels

• ideaIdrequired

  string

  The idea ID from list_ideas

• imageUrlrequired

  string

  Public URL of the image

Turn an existing video idea or community post idea into a new one: a different angle, a Short, a series, a hot take, a beginner version, or a collab. Returns a new title and why it works. Use it on any idea, for example one from get_today_briefing or the Ideas Manager. Needs a paid TubeMagic plan. Allows 100 repurposes per 24 hours for each source.

• titlerequired

  string

  The original idea title

• description

  string

  Why the original idea works, if known

• type

  enum · default "different-angle"

  different-angle = Different Angle (Fresh perspective on same topic), make-short = Make it a Short (Adapt for YouTube Shorts), series = Series Expansion (Turn into a multi-part series), controversial = Hot Take (Add a provocative spin), beginner = Beginner Friendly (Reframe for newcomers), collab = Collab Concept (Reimagine as a collab)

• channelName

  string

  Optional channel name or handle the idea is for

• from

  enum · default "video-idea"

  Where the idea came from: video-idea or community-post

Generate chapter timestamps (like "00:00 - Introduction") for a YouTube video from its transcript, ready to paste into the description. Works for videos up to 60 minutes long that have captions. Needs a paid TubeMagic plan. Allows 100 per 24 hours.

• videoUrlrequired

  string

  A YouTube video URL, like https://youtu.be/VIDEO_ID

The Today page for a connected YouTube channel: subscribers, average views, views and uploads in the last 28 days, and the latest video with its outlier score. Also lists every connected channel.

• channelId

  string

  Connected channel ID (from get_today_overview). Defaults to the first connected channel

Today's daily briefing for a connected channel, the same as the Today page: breakout videos in the channel's niche this week and 3 video ideas for today, each with why it should work, the video that inspired it and a generated thumbnail. The briefing is made once a day; the first call of the day can take up to a minute. Needs a paid TubeMagic plan.

• channelId

  string

  Connected channel ID (from get_today_overview). Defaults to the first connected channel

• retry

  boolean

  Try again after a failed briefing

Save one of today's ideas to the Daily Ideas folder in the Ideas Manager, with its reason, source video and thumbnail. Saving twice keeps one copy.

• ideaIdrequired

  string

  An idea id from get_today_briefing

Mark one of today's ideas as written, for example after writing its script.

• ideaIdrequired

  string

  An idea id from get_today_briefing

List the YouTube channels connected to the user's TubeMagic account (My Channels), with subscribers, video count, and average views. Up to 10 channels can be connected.

No parameters

Search YouTube for channels by name or handle, to find one to connect. Each result says whether it is already connected.

• queryrequired

  string

  Channel name or handle to search for

Connect a YouTube channel to the user's My Channels so TubeMagic tracks its videos and stats. Up to 10 channels. A connected channel can only be disconnected after 90 days, so confirm with the user first. Connecting a channel that is already connected does nothing.

• channelrequired

  string

  The channel ID (UC...), a handle like @mkbhd, or a channel URL

Disconnect a YouTube channel from the user's My Channels. Only possible 90 days after it was connected. Confirm with the user first.

• channelrequired

  string

  A connected channel: its channel ID, handle like @mkbhd, or name

List videos of a connected channel with views and Outlier Score (views divided by the channel average; above 1 means it beat the average). Supports search, time range, sorting, and pages.

• channelrequired

  string

  A connected channel: its channel ID, handle like @mkbhd, or name

• search

  string

  Text to match in video titles

• timeRange

  enum · default "all"

  Published within: all = All time, 7d = Last 7 Days, 30d = Last 30 Days, year = Last Year

• sort

  enum · default "latest"

  Sort by: latest = Latest, oldest = Oldest, most_views = Most views, least_views = Least views, outlier = Outlier Score

• page

  integer · default 1

• limit

  integer · default 12

  Videos per page, up to 24

Totals across all of the user's connected channels: subscribers, views, indexed videos, average views and likes per video, and the latest upload date.

No parameters

Get full details of a video from one of the user's connected channels: views, likes, duration, publish date, and description.

• videorequired

  string

  A YouTube video ID or URL

Get the user's most recent TubeMagic work, like the dashboard: Agent chats, saved videos, scripts, and thumbnail projects, newest first, with links to open each in TubeMagic.

• limit

  integer · default 10

  Items per type, up to 25

List everything the user generated, like the My Generations page: thumbnails, scripts and upload packages (titles, description, tags), newest first, with links to open each in TubeMagic. Filter by type and search by title.

• types

  enum[]

  Only these types. Leave empty for all

  thumbnailscriptupload-package
• search

  string

  Text to match in titles

• offset

  integer · default 0

  Items to skip. Use nextOffset from the previous page

• limit

  integer · default 20

  Items per page, up to 20

Get the signed-in TubeMagic user: name, email, plan, and remaining credits.

No parameters

List the devices and browsers currently signed in to the user's TubeMagic account, newest first.

No parameters

Sign out one device or browser from the user's TubeMagic account, using a sessionId from list_sessions. Confirm with the user first.

• sessionIdrequired

  string

  The sessionId from list_sessions

List everything the user generated with TubeMagic tools (the Logs page), newest first, with the input and a preview of the output. Filter by tool (see list_usage_log_tools) and date range.

• tool

  string

  Only this tool, by name from list_usage_log_tools

• dateFrom

  string

  Only logs on or after this date or time

• dateTo

  string

  Only logs on or before this date or time

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 20

  Logs per page, up to 50

List the tool names the user has logs for, to filter list_usage_logs.

No parameters

List the user's credit history, newest first: credits spent on tools, added by payments, refunded, or changed by an admin. Also returns the current balance.

• source

  enum

  Only this source: PAYMENT = purchases, PROJECT = tool usage and refunds, ADMIN = admin changes

• dateFrom

  string

  Only logs on or after this date or time

• dateTo

  string

  Only logs on or before this date or time

• page

  integer · default 1

  Page number, starting at 1

• limit

  integer · default 10

  Credit logs per page, up to 50

Show how much of each TubeMagic tool's daily free allowance the user has used in the last 24 hours and how much is left, like Settings > Usage, plus the credit balance. Tools marked availableThrough run inside TubeMagic Agent. Premium models and credit-based tools (thumbnails, Agent replies, video formats) spend credits instead.

No parameters