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=false blocks 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.0 or >=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-mcp

This 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 build

The 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

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=true

The 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

Queue and History Tools

Archive and Metadata Tools

Task Tools

Preset Tools

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 extras accepts only ignore_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-files

prek 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.