# TubeWizz MCP server: setup guide for AI agents

You are reading instructions meant for you, an AI agent, so that you can connect your user to TubeWizz.
TubeWizz is a set of YouTube growth tools: titles, descriptions, tags and thumbnails for videos, Shorts, subtitles, competitor and niche research, and analytics for the user's own channel. The MCP server lets you run those tools for the user from inside this conversation.

Human-readable version of this page: https://tubewizz.com/youtube-mcp

## Rules

- Ask the user before you change any settings or config file.
- Never ask the user for a password, API key or token. Sign-in happens in a browser window that TubeWizz opens; the user approves access there.
- Tools marked with a credit cost spend the user's TubeWizz credits. Tell the user the cost and get a yes before you call one.
- Every call to a credit tool starts a new run and charges again, even with the same inputs. After an error or a timeout, check the result link or `get_job_result` before retrying, so you don't run (and charge) twice.
- Only `publish_to_youtube`, `shorts_queue` (approve), `shorts_automation` (set/enable) and `shorts` with `publishMode: "auto"` put anything on the user's YouTube channel. Call them without `confirm` first, show the user the preview they return, and send `confirm: "yes"` only after they explicitly approve. Never approve on their behalf.

## 1. Server

- URL: `https://mcp.tubewizz.com/mcp`
- Transport: Streamable HTTP (remote server, nothing to install)
- Auth: OAuth 2.1 with dynamic client registration. Your client discovers the endpoints from the server; no client ID or secret needs to be entered.
- Account: the user needs a TubeWizz account. Signing up is free and needs no card: https://app.tubewizz.com/login

## 2. Connect, for the client you are running in

Find your client below and follow its steps. If you cannot change your own configuration, show the user the steps and wait for them to finish.

### Claude (claude.ai web and Claude Desktop)

1. The user opens Settings → Connectors → Add custom connector.
2. Name: `TubeWizz`. URL: `https://mcp.tubewizz.com/mcp`.
3. The user clicks Connect, signs in to TubeWizz and clicks Allow.

### Claude Code

```bash
claude mcp add --transport http --scope user tubewizz https://mcp.tubewizz.com/mcp
```

Then run `/mcp`, select `tubewizz` and sign in.

### Cursor

Add this to `~/.cursor/mcp.json` (create the file if it does not exist, and merge with any existing `mcpServers`):

```json
{
  "mcpServers": {
    "tubewizz": {
      "url": "https://mcp.tubewizz.com/mcp"
    }
  }
}
```

Cursor then shows a sign-in prompt for `tubewizz` in Settings → MCP.

### VS Code (GitHub Copilot agent mode)

Add this to `.vscode/mcp.json` in the workspace, or to the user `mcp.json`:

```json
{
  "servers": {
    "tubewizz": {
      "type": "http",
      "url": "https://mcp.tubewizz.com/mcp"
    }
  }
}
```

Start the server from the file and sign in when VS Code asks.

### Codex

```bash
codex mcp add tubewizz --url https://mcp.tubewizz.com/mcp
codex mcp login tubewizz
```

### Gemini CLI

Add this to `~/.gemini/settings.json`, merged with any existing `mcpServers`:

```json
{
  "mcpServers": {
    "tubewizz": {
      "httpUrl": "https://mcp.tubewizz.com/mcp"
    }
  }
}
```

Then run `/mcp auth tubewizz` and sign in.

### ChatGPT

ChatGPT connects to custom MCP servers in developer mode on paid plans. The user enables developer mode in Settings, creates a connector and pastes the server URL above, then signs in to TubeWizz.

### Any other MCP client

Add a remote MCP server with the URL `https://mcp.tubewizz.com/mcp` over Streamable HTTP. The client must support OAuth; there is no API-key option.

## 3. Check the connection

1. Call `get_credit_balance`. A plan and a credit count mean you are signed in.
2. Call `list_channels`. It returns the user's brands with their brandId.

If `list_channels` says there are no brands, the user creates one at https://app.tubewizz.com/brands/new. Connecting their YouTube channel to the brand unlocks the analytics tools and one-time starter credits.

## 4. First run

Tell the user which channels you can see, then ask what they want to work on first. Good openers:

- "Want me to look at how your last videos performed?" (free: `get_brand_metrics`, `get_retention`)
- "Do you have a video coming up that needs a title, description and tags?" (`seo`)
- "Should I compare your channel with a few channels you look up to?" (`competitors`)
- "Want me to rewrite the title and thumbnail of one of your videos and, once you approve, update it on YouTube?" (`seo` or `thumbnails`, then `publish_to_youtube`)

## 5. Tools

### Your account and channel (free)

- `list_channels`: Lists your TubeWizz brands with their brandId. Call this first; most tools take a brandId (optional when you have one brand).
- `get_credit_balance`: Credits left and current plan.
- `get_brand_metrics`: Subscribers, total views and video count of a brand's linked YouTube channel.
- `get_revenue`: Revenue, CPM and RPM for the last 7, 30, 90 or 365 days. Needs YouTube connected and a monetized channel.
- `get_retention`: Average hook rate and view duration, plus the lowest-retention videos.
- `get_niche_breakdown`: The channel's videos grouped by niche, ranked by views.
- `get_geography`: Top countries by views for the last 30, 90 or 365 days.
- `list_videos`: The latest videos on the user's connected channel (also private, unlisted and scheduled ones) with videoId, visibility, date, length and views. Optional `query` matches a word in the title. Use it to find the video for `publish_to_youtube`.
- `get_job_result`: The finished output of an SEO Wizard run (titles, description, chapters, tags) by jobId.
- `get_thumbnail_result`: The finished thumbnails of a Thumbnail Maker run as images, by jobId.

### Public YouTube lookups (free, work on any channel or video)

- `youtube_channel_id`: the channel ID of any channel. Pass `q`: a channel URL, @handle, channel ID, or a link to one of its videos.
- `youtube_subscriber_count`: the subscriber count of any channel. Pass `q`: a channel URL, @handle, channel ID, or a link to one of its videos.
- `youtube_video_tags`: the video tags of any public video. Pass `q`: a video link.
- `youtube_region_check`: the region restriction of any public video. Pass `q`: a video link.
- `youtube_monetization_check`: the monetization eligibility of any channel. Pass `q`: a channel URL, @handle, channel ID, or a link to one of its videos.
- `youtube_video_stats`: the video stats of any public video. Pass `q`: a video link.
- `youtube_earnings_estimate`: the earnings estimate of any channel. Pass `q`: a channel URL, @handle, channel ID, or a link to one of its videos.
- `youtube_video_description`: the video description of any public video. Pass `q`: a video link.
- `youtube_channel_avatar`: the channel avatar of any channel. Pass `q`: a channel URL, @handle, channel ID, or a link to one of its videos.
- `youtube_status`: YouTube status. No input.

### Create, optimize and research (use credits)

- `thumbnails` (Thumbnail Maker, 3 credits): Generate 3 AI-scored thumbnail variants from a topic, optionally with your face and a style reference.
- `similar_titles` (Similar Titles, 1 credit): Analyze a video link or a title → the winning title format on that topic, real high-performing examples, and brand-tuned title variations.
- `bio` (Bio Optimizer, 1 credit): Rewrite the channel bio into 3 tones (professional / casual / story). Auto-fetches the current bio from the linked YouTube channel.
- `srt` (SRT Generator, 1 credit (2 when translating)): Generate a subtitle file (.srt) from a YouTube video — optionally translated to another language.
- `shorts` (Shorts Maker, 2 credits): Turn a long YouTube video into 3 vertical short clips with captions.
- `thumb_translate` (Thumb Translate, 1 credit): Translate the text on a YouTube video's thumbnail into another language.
- `seo` (SEO Wizard, 3 credits): Generate titles, description, chapters, tags and thumbnails for a YouTube video.
- `niche_explorer` (Niche Explorer, 1 credit): Discover channels in a niche — surfacing the smaller / lesser-known ones — from a topic query.
- `article` (Video to Article, 1 credit per format (e.g. LinkedIn + X thread = 2 credits)): Turn a YouTube video into ready-to-post content for one or more formats in one run: a website (SEO) article, a LinkedIn post, an X thread and/or an X long-form article. Pass platforms as a comma-separated list, e.g. "linkedin,x_thread" (or "all"). The formats are written once the transcript is ready; open the result link to read, edit and copy them.
- `playlists` (Playlist Optimizer, 1 credit): Optimize a YouTube playlist — title, description and video order.
- `collab` (Collab Potential, 1 credit): Find channels that are a good fit for a collaboration, from your topic keywords.
- `competitors` (Competitor Analysis, 1 credit): Compare your channel against 1-4 rivals (paste their channel links).
- `trends` (Trend Finder, 1 credit): Research a topic on YouTube — competition, opportunities, tags and winning title formats.
- `comments` (Comment Analysis, 1 credit): Analyze a YouTube video's comments — topics, sentiment, action items and timeline reactions.

You do not need to collect every parameter up front. Call the tool with what you know; if something required is missing, the tool says what to ask the user. Brand defaults (language, Brand Kit) are filled in automatically.

Generation tools start a job and return a jobId. Thumbnails and SEO Wizard runs can take a minute or two: fetch the output with `get_thumbnail_result` or `get_job_result`.

### Publish to the user's channel (free, asks first)

- `publish_to_youtube`: Updates the title, description, tags and/or thumbnail of an existing video on the user's own channel, from an SEO Wizard result (`jobId`), a Thumbnail Maker result (`thumbnailJobId`) or text you pass. The first call without `confirm` returns a current-vs-new preview and changes nothing; call again with `confirm: "yes"` only after the user approves that preview. It never uploads videos, never changes visibility and never deletes anything.
- `shorts_queue`: Lists Shorts waiting for approval, queued, scheduled or published on the user's channel, and approves, rejects, cancels or edits (title, description, tags) them by id. Approving returns a preview first; send `confirm: "yes"` only after the user approves it.
- `community_posts`: Community posts TubeWizz prepared for new videos (text + square AI image) and the per-brand rule that writes them. YouTube has no API for community posts, so the user copies each one into YouTube's Posts tab; mark it `posted` or `dismiss` afterwards. `set` / `enable` return a preview first and need `confirm: "yes"`.
- `shorts_automation`: A standing rule per brand: each new long video on the channel becomes Shorts (2 credits each time) — right away or `delayHours` after it goes public — published after approval or automatically on a schedule. `set` and `enable` return a preview first and need `confirm: "yes"` after the user approves.
- `shorts` also takes an optional publishing plan (`publishMode` approve/auto, `privacy`, `cadence` daily/now, `time`, `timezone`, `clips`) to upload the finished Shorts to the user's channel. YouTube allows only a few uploads per day, so extra Shorts upload on the following days.

## 6. Troubleshooting

- **401 or "Not authenticated"**: the sign-in expired or was never finished. Reconnect the server in the client and sign in again.
- **Not enough credits**: tell the user. Credits are added at https://app.tubewizz.com/billing; free tools keep working.
- **"No brands" / missing brandId**: call `list_channels`; if it is empty, the user creates a brand first.
- **Analytics tools return no data**: the brand's YouTube channel is not connected yet, or the weekly sync has not run. The user connects YouTube on the brand page at https://app.tubewizz.com/brands.
- **Anything else**: support@tubewizz.com
