Mytube

中文

mytube-mcp is a standalone Model Context Protocol server for MyTube. It translates MCP tools, resources, and prompts into authenticated calls to MyTube’s existing /api/* HTTP API. It does not access MyTube’s database or filesystem directly.

Quick start

Requirements: Node.js 20 or newer and a reachable MyTube 1.10.x server.

After this package is published to npm, the shortest installation is:

npx -y mytube-mcp

To run the public repository immediately from source:

git clone https://github.com/franklioxygen/mytube-mcp.git
cd mytube-mcp
npm install
npm run build
npm start

Set the configuration in the MCP client process environment. The recommended least-privilege setup uses an API key:

{
  "mcpServers": {
    "mytube": {
      "command": "npx",
      "args": ["-y", "mytube-mcp"],
      "env": {
        "MYTUBE_BASE_URL": "https://mytube.example.com",
        "MYTUBE_AUTH_MODE": "api-key",
        "MYTUBE_API_KEY": "replace-with-your-mytube-api-key"
      }
    }
  }
}

For collection management, subscriptions, queue control, metadata edits, or uploads, use admin-session mode:

{
  "mcpServers": {
    "mytube": {
      "command": "npx",
      "args": ["-y", "mytube-mcp"],
      "env": {
        "MYTUBE_BASE_URL": "https://mytube.example.com",
        "MYTUBE_AUTH_MODE": "admin-session",
        "MYTUBE_ADMIN_PASSWORD": "replace-with-your-admin-password"
      }
    }
  }
}

The server keeps admin cookies and CSRF tokens in memory only. If MyTube has password login disabled, admin-session mode detects owner mode and proceeds without a password; otherwise MYTUBE_ADMIN_PASSWORD is required.

What is available

API-key mode exposes only the routes MyTube currently marks allowApiKey: true: download_video, list_videos, get_video, list_collections, and get_system_version. The current MyTube backend does not allow API-key access to /api/search, so search_videos is intentionally admin-only even though the design document’s MVP appendix listed it in the API-key catalog.

Admin-session mode adds search, URL inspection, progress/history, queue control, library mutations, uploads, collections, subscriptions, continuous-download tasks, maintenance, cloud signed URLs, resources, and prompts. Destructive tools are annotated and can be further restricted with MCP_ALLOWED_TOOLS.

download_video returns immediately by default. Set await_completion: true to poll MyTube’s active/queued/history endpoints and emit MCP notifications/progress when the client supplies a progress token. Polling is bounded by MYTUBE_DOWNLOAD_POLL_TIMEOUT_MS.

Configuration

Copy .env.example for the complete list. Important settings:

• MYTUBE_BASE_URL is required. HTTPS is required for remote MyTube servers; local HTTP is allowed for localhost/127.0.0.1/*.local, or explicitly with MYTUBE_ALLOW_INSECURE_TLS=true.
• MYTUBE_AUTH_MODE is api-key by default or admin-session.
• MCP_TRANSPORT is stdio by default. Set it to http for Streamable HTTP.
• MCP_UPLOAD_ROOTS must contain one or more directories before upload tools are enabled operationally. Symlink escapes are rejected.
• MYTUBE_ALLOW_INTERNAL_URLS=true is required if trusted LAN/private URLs must be sent to MyTube.

Streamable HTTP

MCP_TRANSPORT=http \
MCP_HTTP_BIND=127.0.0.1 \
MCP_HTTP_PORT=3100 \
MCP_HTTP_BEARER_TOKEN='use-a-long-random-token' \
npx -y mytube-mcp

The endpoint is POST /mcp and the health check is GET /healthz. Bind to loopback by default. For remote access, put the server behind TLS termination and set MCP_HTTP_BEARER_TOKEN; non-loopback binds without a bearer token are rejected. See docs/transport.md.

Docker

A multi-arch image (linux/amd64, linux/arm64) is published to the GitHub Container Registry on every release:

docker pull ghcr.io/franklioxygen/mytube-mcp:latest

Run it in Streamable HTTP mode (Docker only makes sense for the HTTP transport, not stdio):

docker run --rm -p 127.0.0.1:3100:3100 \
  -e MYTUBE_BASE_URL=https://mytube.example.com \
  -e MYTUBE_AUTH_MODE=api-key \
  -e MYTUBE_API_KEY=replace-with-your-mytube-api-key \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_BIND=0.0.0.0 \
  -e MCP_HTTP_PORT=3100 \
  -e MCP_HTTP_BEARER_TOKEN=use-a-long-random-token \
  ghcr.io/franklioxygen/mytube-mcp:latest

Tags follow semantic versioning (0, 0.1, 0.1.0) plus latest. See examples/docker-compose.streamable-http.yml for a Compose setup, or build locally with docker build -t mytube-mcp ..

Development

npm install
npm run build
npm run lint
npm test

See SECURITY.md for the threat model and docs/tools.md for the tool catalog.

Compatibility note

The implementation was compared with MyTube v1.10.11 at the time of this release. MyTube returns raw arrays/objects on several legacy-compatible endpoints, so the client accepts both those responses and the documented { success, data } envelope. It uses MyTube’s actual mytube_auth_session and mytube_csrf cookie names and X-CSRF-Token header.

License

MIT. See LICENSE if this repository is distributed with a license file.