# Algrow MCP Server — Full Documentation Connect Algrow's YouTube intelligence directly to Claude. Search channels, find viral videos, scrape YouTube data, generate TTS audio, create AI images and videos, manage workspace folders and alerts, and manage voices through natural conversation. **Version:** 0.1.0 **Requires:** Algrow API key (Professional or Ultimate plan) --- ## Setup One-liner for Claude Code: ```bash claude mcp add algrow --transport http https://mcp.algrow.online/mcp --header "Authorization: Bearer your-api-key-here" ``` Or add to `.mcp.json` in your project root: ```json { "mcpServers": { "algrow": { "type": "http", "url": "https://mcp.algrow.online/mcp", "headers": { "Authorization": "Bearer your-api-key-here" } } } } ``` For Claude Desktop, add the following to `claude_desktop_config.json` (requires Node.js for `npx`): ```json { "mcpServers": { "algrow": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://mcp.algrow.online/mcp", "--header", "Authorization: Bearer your-api-key-here" ] } } } ``` Config file location: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` Or open it from Claude Desktop via Settings > Developer > Edit Config. Restart Claude Desktop completely after saving. --- ## Tools ### search_shorts_channels Find competitors and similar Shorts channels. Pass a channel name, @handle, YouTube URL, or video URL as `q` to find similar channels. Returns channel metadata, growth metrics, and recent videos. A search query is required. **Parameters:** - `q` (string, required): Accepts: channel ID (UCxxxxx), @handle, channel URL, YouTube video URL (youtube.com/watch?v=, youtube.com/shorts/, youtu.be/), or topic keywords. Pass ANY of these DIRECTLY as-is. Comma-separated for multiple terms, prefix with `-` to exclude. - `sort` (string, optional): Sort: `{field}_{asc|desc}`. Fields: subs, views, videos, age, added, views_24h, subs_24h, views_48h, similarity. Defaults to similarity when searching. - `page` (integer, default 1): Page number (1-indexed, max 20) - `min_subs` / `max_subs` (integer, optional): Subscriber count range - `min_avg_views` / `max_avg_views` (integer, optional): Average views per video range - `min_age` / `max_age` (integer, optional): Channel age in days range - `min_uploads` / `max_uploads` (integer, optional): Number of videos range - `min_views` / `max_views` (integer, optional): Total view count range - `min_views_24h` / `max_views_24h` (integer, optional): Views gained in last 24 hours range - `min_views_48h` / `max_views_48h` (integer, optional): Views gained in last 48 hours range - `min_days_added` / `max_days_added` (integer, optional): Days since channel was added to Algrow's database (NOT channel age) --- ### search_longform_channels Find competitors and similar Longform channels. Pass a channel name, @handle, YouTube URL, or video URL as `q` to find similar channels. Returns channel metadata, growth metrics, monetization status, and recent videos with duration. A search query is required. **Parameters:** - `q` (string, required): Accepts: channel ID (UCxxxxx), @handle, channel URL, YouTube video URL (youtube.com/watch?v=, youtube.com/shorts/, youtu.be/), or topic keywords. Pass ANY of these DIRECTLY as-is. Comma-separated for multiple terms, prefix with `-` to exclude. - `sort` (string, optional): Sort: `{field}_{asc|desc}`. Fields: subs, views, videos, age, total_views, added, views_24h, subs_24h, views_48h, similarity. Defaults to similarity when searching. - `page` (integer, default 1): Page number (1-indexed, max 20) - `min_subs` / `max_subs` (integer, optional): Subscriber count range - `min_avg_views` / `max_avg_views` (integer, optional): Average views per video range - `min_age` / `max_age` (integer, optional): Channel age in days range - `min_uploads` / `max_uploads` (integer, optional): Number of videos range - `min_duration` / `max_duration` (integer, optional): Average video duration in seconds range - `monetized` (string, optional): Filter by monetization: "yes" or "no" - `min_views_24h` / `max_views_24h` (integer, optional): Views gained in last 24 hours range - `min_views_48h` / `max_views_48h` (integer, optional): Views gained in last 48 hours range - `min_days_added` / `max_days_added` (integer, optional): Days since channel was added to Algrow's database (NOT channel age) --- ### search_viral_videos Find related/similar videos by content. This is the PRIMARY tool for finding videos related to a YouTube video or topic. Accepts a YouTube URL directly via `video_url`, or a text search query via `search`. Either `search` or `video_url` is required. Filter by video views, channel size, growth metrics, upload recency, and language. **Parameters:** - `search` (string, optional): Text search query — uses title similarity matching. Pass exact video titles, not paraphrased keywords. One of `search` or `video_url` is required. - `video_url` (string, optional): YouTube video URL (watch, shorts, or youtu.be link). Finds similar videos based on the given video. One of `search` or `video_url` is required. - `content_type` (string, default "shorts"): Content type: "shorts" or "longform" - `channel_ids` (string, optional): Comma-separated channel IDs to filter by (e.g. from a prior search_shorts_channels result). Only returns viral videos from these specific channels. - `languages` (string, optional): Filter by language. Comma-separated (e.g. "English,Spanish"). Defaults to English if omitted. - `sort_by` (string, default "similarity"): Sort: "similarity" (most similar — best for finding relevant videos), "views" (most viewed), "recent" (newest fetched), "upload_date" (newest uploaded). Defaults to similarity. - `page` (integer, default 1): Page number (1-indexed, max 20) - `per_page` (integer, default 50): Results per page (max 50) - `min_video_views` (integer, default 25000) / `max_video_views` (integer, optional): Video view count range. Default min of 25000 matches the system's natural floor. - `min_subs` / `max_subs` (integer, optional): Channel subscriber count range - `min_uploads` / `max_uploads` (integer, optional): Channel video count range - `min_channel_age` / `max_channel_age` (integer, optional): Channel age in days range - `uploaded_within_days` (integer, optional): Only include videos uploaded within this many days. Example: 7 = last week, 30 = last month. - `uploaded_before_days` (integer, optional): Exclude videos newer than this many days ago. Example: 7 = only show videos older than 1 week. - `min_duration` / `max_duration` (integer, optional): Video duration in seconds range (longform only) - `min_views_24h` / `max_views_24h` (integer, optional): Channel views gained in last 24h (shorts only) - `min_views_48h` / `max_views_48h` (integer, optional): Channel views gained in last 48h (shorts only) - `min_similarity` (integer, optional): Minimum similarity score (0-100). Only return videos with at least this similarity %. --- ### search_by_thumbnail Search for longform videos by VISUAL thumbnail similarity. Use this ONLY when the user explicitly asks about thumbnails, thumbnail styles, or thumbnail research — NOT for finding related/similar videos by content (use search_viral_videos for that). Provide a YouTube video URL, an image URL, or a text description/niche. **Parameters:** - `image_url` (string, optional): URL of a thumbnail image to search with. Finds longform videos with visually similar thumbnails. - `video_url` (string, optional): YouTube video URL. Accepts watch, shorts, and youtu.be links. - `q` (string, optional): Text description of what the thumbnails look like, or a niche/topic to find thumbnails for (e.g. "red arrow pointing at shocked face", "before and after transformation", "everything explained", "cooking recipe"). - At least one of `image_url`, `video_url`, or `q` is required. - `limit` (integer, default 50): Max results to return (1-50) - `min_similarity` (float, default 0.3): Minimum similarity threshold 0-1 - `min_views` (integer, optional): Minimum video view count filter - `max_views` (integer, optional): Maximum video view count filter - `uploaded_within_days` (integer, optional): Only include videos uploaded within this many days. Example: 7 = last week, 30 = last month. - `uploaded_before_days` (integer, optional): Exclude videos newer than this many days ago. Example: 7 = only show videos older than 1 week. --- ### search_terminated_channels Search terminated/deleted YouTube channels. Returns channel metadata, growth metrics at time of termination, and top videos. Available on all plans. A search query is required. **Parameters:** - `q` (string, required): Search query. Matches channel titles and video titles. Comma-separated for multiple keywords. - `languages` (string, optional): Filter by language. Comma-separated (e.g. "English,Spanish") - `sort` (string, default "date_desc"): Sort: `{field}_{asc|desc}`. Fields: subs, views, videos, age, views_24h, subs_24h, views_48h, date, similarity - `page` (integer, default 1): Page number (1-indexed, max 20) - `per_page` (integer, default 50): Results per page (max 50) - `min_subs` / `max_subs` (integer, optional): Subscriber count range - `min_views` / `max_views` (integer, optional): Total view count range - `min_avg_views` / `max_avg_views` (integer, optional): Average views per video range - `min_age` / `max_age` (integer, optional): Channel age in days range - `min_uploads` / `max_uploads` (integer, optional): Number of videos range - `monetized` (string, optional): Filter by monetization: "yes" or "no" --- ### search_terminated_by_thumbnail Search terminated/deleted channel videos by VISUAL thumbnail similarity. Same as search_by_thumbnail but searches the terminated channels archive instead of active longform channels. **Parameters:** - `image_url` (string, optional): URL of a thumbnail image to search with. Finds terminated channel videos with visually similar thumbnails. - `video_url` (string, optional): YouTube video URL. Accepts watch, shorts, and youtu.be links. - `q` (string, optional): Text description of what the thumbnails look like, or a niche/topic to find thumbnails for (e.g. "red arrow pointing at shocked face", "before and after transformation"). - At least one of `image_url`, `video_url`, or `q` is required. - `limit` (integer, default 50): Max results to return (1-50) - `min_similarity` (float, default 0.3): Minimum similarity threshold 0-1 - `min_views` (integer, optional): Minimum video view count filter - `max_views` (integer, optional): Maximum video view count filter --- ### scrape_youtube Scrape video data from a YouTube channel or single video. Returns metadata, transcript URLs (hosted .txt files), and top comments (sorted by likes). Async — submits a job, polls until complete, returns final results. **Parameters:** - `url` (string, required): YouTube channel URL or video URL - `video_type` (string, default "both"): Type of videos: "shorts", "videos", or "both" - `sort` (string, default "recent"): Sort order: "recent" or "popular" - `max_videos` (integer, default 20): Maximum videos to scrape (1-100) - `include_transcripts` (boolean, default false): Include video transcripts - `include_comments` (boolean, default false): Include top comments for each video **Note:** Transcripts are returned as `transcript_url`. To read the full transcript text, call the `read_transcript` tool with the URL. Comments limited to 20 per video (top by likes, 300 chars each). --- ### read_transcript Fetch full transcript text for YouTube videos. Pass one or more `transcript_url` values from scrape_youtube results (comma-separated for batch). All URLs are fetched in parallel. Returns complete transcripts with no truncation. **Parameters:** - `transcript_url` (string, required): One or more transcript_url values from scrape_youtube results. Pass a single URL or multiple comma-separated URLs to fetch all in parallel (e.g. "https://audio.algrow.online/api/transcripts/abc.txt,https://audio.algrow.online/api/transcripts/def.txt"). --- ### resolve_handle Resolve a YouTube @handle to a stable channel ID (UCxxxxxxxxxxxxxxxxxxxxxx). This tool exists for ONE narrow purpose: getting a channel_id to pass to save_channels (which requires a UCxxx ID, not a handle). Do NOT use it for finding, searching, or discovering channels — search_shorts_channels and search_longform_channels accept @handles directly and resolve them internally. **Parameters:** - `handle` (string, required): A YouTube @handle (e.g. "@cheftok" or "cheftok"). The leading @ is optional. --- ### resolve_url Resolve a YouTube channel URL or video URL to a stable channel ID (UCxxxxxxxxxxxxxxxxxxxxxx). This tool exists for ONE narrow purpose: getting a channel_id to pass to save_channels (which requires a UCxxx ID, not a URL). Do NOT use it for finding, searching, or analyzing channels — search_shorts_channels, search_longform_channels, and search_viral_videos all accept URLs directly and resolve them internally. **Parameters:** - `url` (string, required): A YouTube channel URL (youtube.com/@handle, youtube.com/channel/UCxxx) OR a video URL (watch/shorts/youtu.be) — for video URLs the owner channel is returned. --- ### list_folders List the user's saved folders with channel counts. Use this at the start of a session to see what folders exist, before save_channels to check if a target folder already exists, or to resolve a folder name to its ID. Returns folder name, ID, channel count, and creation date for each folder. No parameters required. --- ### create_folder Create a new folder for organizing saved channels. Returns 409 if a folder with this name already exists. Returns 403 if the user has hit their plan-tier folder limit (Starter: 15, Pro: 50, Ultimate: unlimited). **Parameters:** - `name` (string, required): Folder name (1-50 chars, must be unique per user) --- ### rename_folder Rename an existing folder. Returns 409 if the new name collides with another existing folder. **Parameters:** - `folder` (string or integer, required): Current folder name OR folder ID - `new_name` (string, required): New folder name (1-50 chars, must be unique) --- ### delete_folder Delete a folder AND unsave every channel in it. This is destructive. The first call (confirm=false) returns the folder's channel count so you can warn the user. Only set confirm=true after the user explicitly says yes. There is no Uncategorized fallback — channels in the folder are unsaved permanently. **Parameters:** - `folder` (string or integer, required): Folder name OR folder ID to delete - `confirm` (boolean, default false): Set to true to confirm deletion. First call returns the channel count so you can warn the user before they confirm. --- ### get_folder Get all channels in a folder with LIVE 24h growth metrics. Returns each channel's current subscriber count, view count, AND the latest 24h delta (views_24h, subs_24h). Channels with no recent snapshot will have NULL views_24h/subs_24h fields. **Parameters:** - `folder` (string or integer, required): Folder name OR folder ID --- ### save_channels Save one or more channels to a folder. channel_ids must be raw YouTube channel IDs (start with "UC", 24 chars). For @handles or URLs, call resolve_handle / resolve_url first. folder is REQUIRED — if the user didn't name one, ask them. There is no default folder. 30 channels per folder hard cap, all plans. **Parameters:** - `channel_ids` (list of strings, required): List of YouTube channel IDs (UCxxxxxxxxxxxxxxxxxxxxxx). Must be raw IDs — call resolve_handle or resolve_url first to convert @handles or URLs. - `folder` (string or integer, required): Folder name OR folder ID. If the user didn't specify a folder, ASK them — there is no default folder. --- ### unsave_channel Remove a channel from the user's saved set. The channel disappears from whichever folder it was in. **Parameters:** - `channel_id` (string, required): YouTube channel ID (UCxxxxxxxxxxxxxxxxxxxxxx) to remove from saved channels --- ### move_channel Move an already-saved channel from its current folder to a different one. Returns 404 if the channel isn't currently saved. Returns 409 if the target folder is at the 30-channel cap. No-op (200) if the channel is already in the target folder. **Parameters:** - `channel_id` (string, required): YouTube channel ID (UCxxxxxxxxxxxxxxxxxxxxxx) to move - `to_folder` (string or integer, required): Destination folder name OR folder ID --- ### list_alerts List all the user's active alerts (paused and unpaused). Use this when the user asks "what alerts do I have" or before deleting/pausing an alert by description (find the right ID first). No parameters required. --- ### create_alert Create a growth alert. Fires once a night when the threshold is crossed. Three target types: channel (single channel), folder (any channel in a folder), search (new channels matching a saved search). Plan limits: Starter 3, Professional 25, Ultimate unlimited. **Parameters:** - `target_type` (string, required): What the alert watches: "channel" (single channel), "folder" (any channel in a folder), or "search" (new channels matching a saved search). - `target_value` (object, required): Shape depends on target_type: `{"channel_id": "UCxxx..."}` for channel, `{"folder_id": 47}` for folder, `{"query": {"q": "cooking", "max_subs": 100000, "content_type": "shorts"}}` for search. For search targets the server FORCES max_days_added=1. - `metric` (string, required): What to measure: "subs_24h" (subscriber gain in last 24h), "views_24h" (view gain), or "new_channels" (count of new search matches — search target only). - `threshold` (integer, required): Fire when the metric value is >= this number. E.g. threshold=5000 with metric="subs_24h" means "fire when channel gains 5000+ subs in 24h". --- ### pause_alert Pause an alert without deleting it. Resume later with unpause_alert. **Parameters:** - `alert_id` (integer, required): Alert ID from list_alerts --- ### unpause_alert Resume a previously paused alert. **Parameters:** - `alert_id` (integer, required): Alert ID from list_alerts --- ### delete_alert Permanently delete an alert. Also deletes all its triggered_alerts history. **Parameters:** - `alert_id` (integer, required): Alert ID from list_alerts --- ### get_triggered_alerts Get the user's alert inbox — the morning-briefing tool. Default behavior: returns alerts that have fired since the user last checked AND atomically marks them as seen. If you call this twice in a row, the second call returns 0 alerts because the first call already drained the inbox. Set include_acknowledged=true for read-only history mode that includes already-seen alerts and does NOT mark new ones as seen. **Parameters:** - `since` (string, optional): Duration filter: "24h", "7d", or "30d". Limits results to alerts that fired within this window. - `include_acknowledged` (boolean, default false): Default false (inbox mode). Set true for read-only history mode that includes alerts you've already seen and does NOT mark new ones as seen. --- ### list_voices Browse and search available TTS voices. Returns voice IDs, names, previews, and metadata. Set stealth=true for Stealth provider voices. **Parameters:** - `search` (string, optional): Search by voice name or labels - `gender` (string, optional): Filter: "male", "female", or "neutral" - `age` (string, optional): Filter: "young", "middle_aged", or "old" - `language` (string, optional): Language code (e.g. "en", "es", "fr") - `accent` (string, optional): Filter by accent (e.g. "american", "british") - `sort` (string, default "trending"): Sort: "trending", "created_date", "usage_character_count_1y" - `page_size` (integer, default 30): Results per page (max 100) - `page` (integer, default 0): Page number (0-indexed) - `stealth` (boolean, default false): Use Stealth voices endpoint instead of ElevenLabs --- ### generate_tts Generate text-to-speech audio. Submits a job, polls until complete, returns the permanent hosted audio URL. **Parameters:** - `script` (string, required): Text to convert to speech (max 200,000 characters) - `voice_id` (string, required): Voice ID from list_voices, or voice name for Stealth provider - `provider` (string, default "elevenlabs"): TTS provider: "elevenlabs" or "stealth" - `model_id` (string, optional): ElevenLabs model: "eleven_multilingual_v2", "eleven_v3", "eleven_turbo_v2_5", "eleven_flash_v2_5", "eleven_turbo_v2", "eleven_flash_v2" - `stability` (float, optional): Voice consistency 0.0-1.0 (ElevenLabs only) - `similarity_boost` (float, optional): Voice match accuracy 0.0-1.0 (ElevenLabs only) - `style` (float, optional): Style exaggeration 0.0-1.0 (ElevenLabs only) - `speed` (float, optional): Playback speed 0.7-1.2 (ElevenLabs only) - `temperature` (float, optional): Expressiveness (Stealth only) - `speaking_rate` (float, optional): Speaking speed multiplier (Stealth only) - `voice_name` (string, optional): Human-readable voice label for your reference - `custom_title` (string, optional): Custom filename for output MP3 (without extension) - `generate_srt` (boolean, default false): Generate SRT subtitle file (ElevenLabs only) --- ### get_tts_job_status Check the status of a TTS generation job. Use this to retrieve audio_url for a previously submitted job. **Parameters:** - `job_id` (string, required): Job ID returned from generate_tts --- ### list_tts_jobs List your recent TTS generation jobs, sorted by creation time (newest first). No parameters required. --- ### clone_voice Clone a voice using the Stealth voice engine. Requires an active subscription. Upload an audio sample and get a reusable voice ID back. **Parameters:** - `display_name` (string, required): Display name for the cloned voice - `audio_url` (string, required): URL to the audio sample (MP3, WAV, M4A, OGG, WEBM; max 15MB) - `lang_code` (string, default "EN_US"): Language code (e.g. "EN_US", "ES_MX", "FR_FR", "DE_DE", "JA_JP", "KO_KR", "ZH_CN", "RU_RU", "AR_SA", "PL_PL", "NL_NL", "HI_IN", "HE_IL") - `description` (string, optional): Description of the voice --- ### delete_voice Delete a cloned Stealth voice by ID. Only voices you own can be deleted. **Parameters:** - `voice_id` (string, required): ID of the cloned voice to delete --- ### generate_image Generate an AI image from a text prompt. Requires Professional or Ultimate plan. Async job — submits, polls, returns result. **Parameters:** - `prompt` (string, required): Description of the image to generate - `model` (string, default "nano-banana-2"): Model: "nano-banana-2" (2 credits), "nano-banana-pro" (3 credits), "seedream-4.5-edit" (2 credits, requires reference_image_url), "seedream-5.0-lite" (2 credits) - `aspect_ratio` (string, default "16:9"): Aspect ratio (e.g. "16:9", "9:16", "1:1", "4:3") - `reference_image_url` (string, optional): Reference image URL. Required for seedream-4.5-edit. --- ### generate_video Generate an AI video from a text prompt. Requires Professional or Ultimate plan. Async job — submits, polls, returns result. **Parameters:** - `prompt` (string, required): Description of the video to generate - `model` (string, default "sora-2"): Model: "sora-2", "kling-2.6", "veo3-fast", "grok-image-to-video" - `seconds` (string, default "4"): Duration in seconds for sora-2 (4, 8, or 12) - `size` (string, default "720x1280"): Resolution for sora-2 (e.g. "720x1280", "1280x720") - `duration` (string, default "5"): Duration for kling-2.6 (5 or 10) - `sound` (boolean, default false): Include audio track (kling-2.6 only, doubles credit cost) - `aspect_ratio` (string, default "9:16"): Aspect ratio for veo3-fast (e.g. "9:16", "16:9") - `input_reference_url` (string, optional): Reference image URL. Required for kling-2.6, grok-image-to-video, veo3-fast. **Credit costs:** sora-2: 13/18/25 (4s/8s/12s), kling-2.6: 8-30 (varies by duration and sound), grok-image-to-video: 3, veo3-fast: 8 --- ### remove_captions Remove captions/watermarks from a video. Costs 12 credits per minute (0.2 per second, rounded up). Max 90 seconds. Async job. **Parameters:** - `video_url` (string, required): URL of the video to remove captions from --- ### remove_sora_watermark Remove the Sora watermark from a video. Costs 2 studio credits. Async job. **Parameters:** - `video_url` (string, required): Sora video URL (must be from sora.chatgpt.com) --- ### health_check Check API health and view current job counts. No authentication required. No parameters. --- ## Example Prompts - "Find English Shorts channels under 10k subs that are less than 90 days old and growing fast" - "Search for longform channels about personal finance with under 50k subs that are monetized" - "Find the top viral Shorts about AI tools uploaded in the last 3 days" - "Search for terminated channels in the gaming niche with over 100k subs" - "Scrape the last 20 videos from @AlexHormozi and include transcripts so I can analyze his content strategy" - "List trending male voices, then generate a voiceover for this script: [paste script]" - "Clone my voice from this audio file and generate a test clip" - "Generate an image of a futuristic cityscape at sunset in 16:9" - "Generate a 4-second Sora video of waves crashing on a beach" - "Remove the captions from this video: [URL]" - "Find 5 viral Shorts about fitness, scrape the top performing channel, and summarize their content strategy" - "Save @MrBeast and @MKBHD to a folder called 'Top Creators'" - "What folders do I have? Show me the channels in my 'Cooking' folder with their 24h growth" - "Set up an alert when any channel in my 'Competitors' folder gains 5000+ subs in 24h" - "Any alerts this morning?" - "Find terminated channels in the fitness niche with thumbnails similar to this video: [URL]"