ytptube-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ytptube-mcp add this video to the download queue"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ytptube MCP Server
A local stdio Model Context Protocol server that lets an MCP client inspect and, when explicitly enabled, manage a self-hosted ytptube HTTP API.
What is this?
This server gives an AI assistant a focused interface to your ytptube instance without putting API credentials in prompts or source control. It can inspect downloads, history, tasks, presets, logs, and service configuration. Changes are disabled by default and are rejected locally before the server makes a network request.
Ask your MCP client things such as:
"Is my ytptube instance reachable?"
"What is downloading right now?"
"Show the latest completed downloads."
"Inspect this video URL before I add it."
"What scheduled tasks are configured?"
"List my download presets."
When you deliberately enable write access, it can also add downloads, manage the queue and history, update tasks and presets, and generate metadata.
Related MCP server: metube-mcp
Features
Safe by default —
YTPTUBE_ALLOW_MUTATIONS=falseblocks every state-changing request before it reaches ytptube.Focused API access — inspect health, configuration, queue/history, archive entries, scheduled tasks, presets, and recent logs.
Validated inputs — download and task URLs must use HTTP or HTTPS; write tools reject raw yt-dlp CLI strings.
Credential-aware — authentication is optional, but the username and password must be configured together and sensitive API results are redacted.
Small deployment surface — standard input/output transport and a configured ytptube HTTP API; no file browser, shell access, notifications, task/preset deletion, or SSE.
Quick start
Prerequisites
Node.js
^20.19.0or>=22.12.0.A reachable self-hosted ytptube HTTP API.
An MCP-compatible client, such as Codex or Claude Desktop.
Install from npm
npm install --global ytptube-mcpThis makes the ytptube-mcp command available on your PATH. Configure the
server through your MCP client's environment, as shown below.
Install from source
git clone https://github.com/Snuffy2/ytptube-mcp.git
cd ytptube-mcp
npm ci
cp .env.example .env
# Edit .env and set YTPTUBE_BASE_URL.
npm run buildThe build produces dist/index.js. Re-run npm run build after changing the
TypeScript source.
At startup, the built server reads the .env file from the checkout that
contains dist/index.js, even when an MCP client starts it from another
directory. Explicit environment variables take precedence over .env.
Configure your MCP client
For an npm installation, use the ytptube-mcp command and keep values specific
to your ytptube instance in its environment configuration:
[mcp_servers.ytptube]
command = "ytptube-mcp"
[mcp_servers.ytptube.env]
YTPTUBE_BASE_URL = "https://media.example.net/ytptube"
YTPTUBE_ALLOW_MUTATIONS = "false"
# Set these two together only when the API requires authentication.
# YTPTUBE_USERNAME = "your-user"
# YTPTUBE_PASSWORD = "your-password"For a source checkout, run its built server with Node. Replace the placeholder with the absolute path to your checkout:
[mcp_servers.ytptube]
command = "node"
args = ["/absolute/path/to/ytptube-mcp/dist/index.js"]The checkout's .env file supplies its configuration. Do not commit actual
credentials or store them in shared shell history.
Environment variables
Variable | Required | Description |
| Yes | Root URL of the ytptube API, including any reverse-proxy path prefix. |
| Together, if needed | Optional HTTP API credentials. Providing only one is a configuration error. |
| No |
|
| No | Request timeout from |
| No | Exact string |
Safety and write access
The server is read-only by default. With YTPTUBE_ALLOW_MUTATIONS=false, a
request such as ytptube_add_downloads returns MUTATIONS_DISABLED locally
and sends no request to ytptube. Read-only inspection tools remain available.
Set the value to the exact string true only for a session that must change
state, then restart the server/client so it receives the new setting. Return
it to false when you are done.
YTPTUBE_ALLOW_MUTATIONS=trueThe gate covers download additions/retries, queue controls, history and archive changes, task and preset changes, and metadata generation. Clearing history does not remove media unless the request explicitly asks for it.
Available Tools
Every tool name begins with ytptube_. Tools marked Yes in the Mutating
column require YTPTUBE_ALLOW_MUTATIONS=true; otherwise the server rejects the
request before contacting ytptube.
Health and Inspection Tools
Tool | Description | Mutating |
| Check whether the configured ytptube API is reachable. | No |
| Read system configuration with sensitive fields redacted. | No |
| Read the active yt-dlp option configuration. | No |
| Parse and validate yt-dlp CLI options without starting a download. | No |
| Inspect URL metadata without adding it to the download queue. | No |
| Read recent application logs when file logging is enabled. | No |
| Read current in-memory queue progress and counts. | No |
Queue and History Tools
Tool | Description | Mutating |
| List a paginated queue or completed-history page. | No |
| Read one queue or history item by ID. | No |
| Add one or more URLs to the download queue. | Yes |
| Requeue a history item using only its saved download-request fields. | Yes |
| Start, pause, force-start, reorder, or cancel queued downloads. | Yes |
| Delete selected queue/history records; media deletion is opt-in. | Yes |
Archive and Metadata Tools
Tool | Description | Mutating |
| List archive entries for a preset, optionally filtered by archive IDs. | No |
| Archive or unarchive a history item using its configured archive file. | Yes |
| Generate task metadata, NFO, and image sidecar files. | Yes |
| Generate an NFO sidecar for a completed history item. | Yes |
Task Tools
Tool | Description | Mutating |
| List scheduled tasks with pagination. | No |
| Read a scheduled task by numeric ID. | No |
| Preview task handling and items for a URL without queuing downloads. | No |
| Create one or more scheduled tasks. | Yes |
| Partially update a scheduled task. | Yes |
| Replace a scheduled task using the API PUT contract. | Yes |
Preset Tools
Tool | Description | Mutating |
| List download presets with pagination and sorting. | No |
| Read a download preset by numeric ID. | No |
| Create a download preset. | Yes |
| Partially update a non-default download preset. | Yes |
| Replace a non-default download preset using the API PUT contract. | Yes |
Important limits
Task URL inspection is a preview; ytptube does not offer a scheduled-task "run now" endpoint.
Global yt-dlp options are read-only through this server.
Write tools do not accept raw yt-dlp CLI strings. The validation tool only parses and validates a string; it never starts a download.
Download
extrasaccepts onlyignore_conditions, a non-empty array of condition names. Use"*"to ignore all conditions.Per-download authentication and settings belong in presets. Task create and update inputs reject arbitrary configuration and cookies.
Development
Install prek to run the repository's
quality hooks or refresh its hooks with the dependency-update script.
# Install dependencies, type-check, test, and build.
./scripts/test.sh
# Run the repository quality hooks.
prek run --all-filesprek is the repository's only linter and formatter. It checks repository
files, GitHub Actions syntax, formatting, and TypeScript types.
Troubleshooting
The server says YTPTUBE_BASE_URL is required. Set a valid HTTP or HTTPS
base URL in the MCP client environment or .env, including any proxy prefix.
Authentication fails. Confirm the URL is correct for your proxy and that
both YTPTUBE_USERNAME and YTPTUBE_PASSWORD are set. Use basic unless
your ytptube API/proxy specifically requires the apikey fallback.
A mutation is unavailable. Confirm it is really required, set
YTPTUBE_ALLOW_MUTATIONS=true, restart the MCP client/server, perform the
operation, and then disable mutations again.
A tool returns redacted values. This is intentional: the server protects credentials and sensitive values when it formats API results and errors.
Contributing
Please open an issue before starting a large change. Keep the stdio transport,
the ytptube HTTP API boundary, and the read-only default intact. Run the local
test script and prek before opening a pull request.
License
This project is licensed under the MIT License.
Available Tools
28 toolsytptube_add_downloadsB
Add one or more URLs to the download queue.
Inputs: items (required).
ytptube_clear_historyADestructive
Delete queue/history records selected by IDs or a status filter; media deletion is opt-in.
Inputs: type (required), ids, status, delete_media.
ytptube_create_presetC
Create a download preset.
Inputs: preset (required).
ytptube_create_tasksC
Create one or more scheduled tasks.
Inputs: tasks (required).
ytptube_generate_history_nfoCDestructive
Generate an NFO sidecar for a completed history item.
Inputs: id (required), type, overwrite.
ytptube_generate_task_metadataB
Generate task metadata, NFO, and image sidecar files.
Inputs: id (required).
ytptube_get_history_itemBRead-onlyIdempotent
Read one queue or history item by ID.
Inputs: id (required).
ytptube_get_presetARead-onlyIdempotent
Read a download preset by numeric ID.
Inputs: id (required).
ytptube_get_system_configurationARead-onlyIdempotent
Read YTPTube system configuration. Sensitive fields are recursively redacted.
Inputs: no named parameters.
ytptube_get_taskARead-onlyIdempotent
Read a scheduled task by numeric ID.
Inputs: id (required).
ytptube_get_ytdlp_optionsARead-onlyIdempotent
Read the active yt-dlp option configuration.
Inputs: no named parameters.
ytptube_inspect_task_urlARead-onlyIdempotent
Preview the task handler and items for a URL; this only calls /api/tasks/inspect and never queues downloads.
Inputs: url (required), preset, handler, static_only.
ytptube_inspect_urlARead-onlyIdempotent
Inspect URL metadata without adding it to the download queue.
Inputs: url (required), force, preset, entries.
ytptube_list_archiveARead-onlyIdempotent
List archive entries for a preset, optionally filtered by archive IDs.
Inputs: preset (required), ids.
ytptube_list_historyCRead-onlyIdempotent
List a paginated queue or completed-history page.
Inputs: type (required), page, order, status, +1 more.
ytptube_list_logsARead-onlyIdempotent
Read recent YTPTube application logs (when file logging is enabled).
Inputs: limit, offset.
ytptube_list_presetsBRead-onlyIdempotent
List download presets with pagination and sorting.
Inputs: page, sort, order, per_page, +1 more.
ytptube_list_tasksARead-onlyIdempotent
List scheduled tasks with pagination.
Inputs: page, per_page.
ytptube_live_queueCRead-onlyIdempotent
Read current in-memory queue progress and counts.
Inputs: limit.
ytptube_patch_presetA
Partially update a non-default download preset.
Inputs: id (required), changes (required).
ytptube_patch_taskB
Partially update a scheduled task.
Inputs: id (required), changes (required).
ytptube_pingARead-onlyIdempotent
Check whether the configured YTPTube API is reachable.
Inputs: no named parameters.
ytptube_queue_controlBDestructive
Start, pause, force-start, reorder, or cancel queued downloads.
Inputs: ids (required), action (required).
ytptube_retry_history_itemB
Read a history item and requeue only saved download-request fields.
Inputs: id (required).
ytptube_set_history_archiveADestructive
Archive or unarchive a history item using its configured archive file.
Inputs: id (required), archived (required).
ytptube_update_presetB
Replace a non-default download preset using the API PUT contract.
Inputs: id (required), preset (required).
ytptube_update_taskB
Replace a scheduled task using the API PUT contract.
Inputs: id (required), task (required).
ytptube_validate_cli_optionsARead-onlyIdempotent
Parse and validate yt-dlp CLI options without starting a download.
Inputs: args (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Every tool has a distinct purpose: reading vs writing, history vs tasks vs presets vs system state. Even the patch/update pairs are clearly differentiated by partial vs full replacement.
All tools use the 'ytptube_' prefix followed by a verb_noun pattern (e.g., list_tasks, create_preset, validate_cli_options). Minor deviations like 'live_queue' are still readable and do not break the overall consistency.
With 28 tools, the server exceeds the 25-tool threshold for 'too many'. While each tool covers a distinct API operation, the sheer number makes the surface area heavy and harder to navigate.
Core download lifecycle and task/preset management are covered, but obvious gaps exist: there is no delete operation for tasks or presets, and system configuration and yt-dlp options are read-only with no set/update functionality.
Maintenance
Related MCP Connectors
MCP server for the FFmpeg Micro video transcoding API — create, monitor, download transcodes.
Real-time YouTube transcripts, comments, channels & video search MCP. Local npx or hosted OAuth.
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA fully functional MCP server and CLI for YouTube to automate YouTube operation.730Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that enables users to control a MeTube instance for managing yt-dlp video and audio downloads through AI assistants. It supports operations like queuing URLs, listing active downloads, and managing authentication cookies.92MIT
- AlicenseNot gradedqualityCmaintenanceA local, privacy-first MCP server providing direct access to official YouTube Data, Analytics, Reporting, and Live Streaming APIs for creators, enabling channel analysis, research, and guarded management operations.4MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for fetching YouTube video transcripts and metadata using yt-dlp. It provides tools for transcript retrieval, subtitle listing, video info, and cookie management to bypass YouTube rate limits.-