tubearchivist-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., "@tubearchivist-mcp search my Tube Archivist archive for Kubernetes videos"
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.
tubearchivist-mcp
MCP connector for a self-hosted Tube Archivist v0.6.0 archive. It calls the JSON API, plus WebVTT subtitles, over stdio and over stateless Streamable HTTP on localhost.
Tube Archivist is GPL-3.0. This connector is MIT. It does not vendor Tube Archivist source, OpenAPI, or documentation text. It is not affiliated with tubearchivist/tubearchivist.
spec/api-inventory.json is a hand-written inventory: method, path, a short purpose in our own words, and read or write. It records v0.6.0, commit 5a18613136122dd8fe83d43d95ea1b8af00d79eb, GPL-3.0, file sha256s, and routeTreeSha256. scripts/gen-operations.mjs maps that inventory onto tool actions or exclusions and writes src/operations.ts and tubearchivist.routes.json. A route that is neither mapped nor excluded fails generation. Do not edit src/operations.ts by hand. npm run ci runs the generator with --check.
TUBEARCHIVIST_URL and TUBEARCHIVIST_TOKEN (or TUBEARCHIVIST_TOKEN_FILE) are required. There is no default origin. Each request sends Authorization: Token <key>. The token is never placed in the URL. This is not a Bearer scheme.
Setup
npm install
npm run ci
npm start
npm run start:httpnpm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.
Create the API token in the Tube Archivist UI (Settings, API token) or with Django REST framework's token model. The header must be Authorization: Token, then a space, then the key.
{
"mcpServers": {
"tubearchivist": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"TUBEARCHIVIST_URL": "http://127.0.0.1:8000",
"TUBEARCHIVIST_TOKEN": "...",
"TUBEARCHIVIST_ALLOW_WRITES": "false"
}
}
}
}Prefer TUBEARCHIVIST_TOKEN_FILE (mode 0600) over TUBEARCHIVIST_TOKEN. The connector never prints the token.
docker build -t tubearchivist-mcp .
docker run -p 127.0.0.1:3000:3000 \
-e TUBEARCHIVIST_URL=http://127.0.0.1:8000 \
-e TUBEARCHIVIST_TOKEN=... \
tubearchivist-mcpDo not put secrets in the image. The image is the connector only. It does not run Elasticsearch, Redis, or Tube Archivist.
Regenerate the registry from the committed inventory.
npm run gen:operations
node scripts/gen-operations.mjs --check
node scripts/gen-operations.mjs --source-root /path/to/tubearchivist --check--source-root checks the pinned file sha256s. It does not rewrite the inventory.
scripts/live-check.mjs talks to a real server over stdio. Set TUBEARCHIVIST_URL. Set TUBEARCHIVIST_TOKEN or TUBEARCHIVIST_TOKEN_FILE. The script unsets DATABASE_URL. It prints pass or fail lines only, and it redacts the token. It does not run inside npm run ci. A missing token is a failure.
Isolated local runtime scripts live under /workspace/tools/tubearchivist (start.sh, stop.sh). Throwaway data stays under /workspace/tools/tubearchivist/runtime. The GPL checkout stays in tools/ and is not part of this package. No Docker.
Related MCP server: audiobookshelf
Config
Variable | Meaning |
| Required. Origin only, |
| Required unless |
| Optional. chmod 600 file whose trimmed contents are the token. Used when |
| Must be the literal |
| Local request budget. Default 30. Cache hits do not spend it. Live-check sets 600. |
| Upstream timeout. Default 20000. |
| Read cache TTL. Default 60. Writes clear the cache. |
| Contact token in the User-Agent. Must not contain the API token. |
|
|
| HTTP port. Default 3000. |
Invalid values are reported by field name and issue code. The rejected value is not included.
Calls go to paths from the operations registry. Accept is application/json except subtitle text. JSON writes send Content-Type: application/json. Redirects are refused. There are no automatic retries, including HTTP 429.
On this v0.6.0 build, a missing or wrong token is HTTP 403, not 401. The connector still maps 401 to unauthorized when an instance sends it.
Tools
Fourteen action-field tools. action selects the operation. Unknown fields and fields that do not belong to that action are rejected before any HTTP call. The string "true" is not a boolean and is rejected. JSON bodies are one object, document. List routes take a page query (integer 0 to 10000) and the connector forwards it. It does not slice the page locally. An empty page value is the server's 404. page=1 is redundant with page 0 on this build. A page past the 10000-hit window is HTTP 400.
Tool | Actions |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Writes (37) need confirm: true and TUBEARCHIVIST_ALLOW_WRITES=true. Deletes, snapshot restore, backup restore, and task command (stop or kill) are marked destructive. Other writes are still gated the same way.
v0.6.0 has no pause route. Queue items use status pending, ignore, ignore-force, or priority. priority on ta_download update or bulk_update is how a download is started. ta_download add accepts autostart, flat, and force queries. Adding an item schedules yt-dlp on the Celery worker. Without that worker the HTTP call can still return "add to queue task started" and the row never appears. Stopping a running task is ta_task command with document.command of stop or kill, and only for tasks the server marks as stoppable.
GET /api/task/by-name/ (ta_task results) returns HTTP 500 HTML on an empty task index in v0.6.0. That is upstream. The connector maps it to upstream and does not retry.
GET /api/health/ needs no token. The body is the JSON string "OK", so the tool returns { "text": "OK" }.
Examples
Ping and search:
{ "action": "ping" }{ "action": "search", "query": "lecture" }Second page of videos on one channel:
{ "action": "list", "page": 2, "channel": "UC_channel_id" }Dry-run a queue add (nothing is sent):
{
"action": "add",
"autostart": false,
"flat": true,
"document": { "data": [{ "youtube_id": "dQw4w9WgxcQ", "status": "pending" }] }
}Send it only when you mean to:
{
"action": "add",
"autostart": false,
"flat": true,
"confirm": true,
"document": { "data": [{ "youtube_id": "dQw4w9WgxcQ", "status": "pending" }] }
}confirm: true still does not send unless TUBEARCHIVIST_ALLOW_WRITES=true.
Safety
Reads run without a write flag. A write is sent only when confirm is the boolean true and TUBEARCHIVIST_ALLOW_WRITES=true. That gate covers all 37 writes: refresh, watched state, video delete and progress, channel subscribe/update/delete, playlist subscribe/create/update/delete, download add/update/delete, task start/command/schedule changes, notification add/remove, config update, cookie validate/import/revoke, snapshots, backups, rescan, manual import, and user preferences.
Omit confirm, or pass boolean false, and the tool returns a dry-run preview of method, path, and body. It sends nothing. blocked is false on that preview. confirm: true with writes disabled returns the same preview with blocked true and the reason TUBEARCHIVIST_ALLOW_WRITES is not true. The write was not sent.
The API token is redacted in logs, errors, previews, and tool results, including percent-encoded and JSON-escaped forms. URL userinfo is stripped. Values under sensitive keys (password, token, secret, cookie, authorization, credential, and the same family) become [redacted]. cookie_enabled and cookie_import are booleans about whether a cookie file is in use, so they stay. The cookie string field cookie is redacted. A short credential (under 8 characters) forces a generic upstream message instead of a partial mask.
Excluded on purpose:
Route | Why |
| Generated OpenAPI and Swagger HTML. Not vendored. |
| Password login and browser session. This connector uses the token header only. |
| Would echo or revoke the connector's own token. |
Membership profile, sync, and token | Paid external account, not the local archive. |
| Sends a request to a caller-supplied URL. |
Video stream and video, channel, and playlist thumbnails | Binary media. Subtitles stay, as WebVTT text. |
Provenance and coverage
Upstream | tubearchivist/tubearchivist v0.6.0, commit |
License (upstream) | GPL-3.0 |
License (this connector) | MIT |
Inventory routes | 95 |
Mapped | 79 |
Excluded | 16 |
Tools | 14 |
Actions | 79 |
Write actions | 37, all confirm-gated |
Public docs were read at https://docs.tubearchivist.com/api/introduction/ for auth, pagination, and error behavior. Route facts were taken from the v0.6.0 URL modules and checked against view methods for query and body fields. No upstream file is copied into this package.
Rivals
Checked 18 Nov 2026. GitHub code and repository search, npm search, and the APIs.io Tube Archivist profile found no MCP server for self-hosted Tube Archivist. APIs.io scores that profile MCP Server 0/12 (profile dated 13 Nov 2026).
Project | What it is | Compared with this connector |
| Remote MCP for a hosted YouTube archive index. Tools: | Not a Tube Archivist instance. No local queue, tasks, or config. Needs their API key. |
TheWhiteWater | YouTube research helper. | Not Tube Archivist and not this API. |
alcor6502/archivist-mcp | Git-backed markdown vault. | Unrelated product that shares the word archivist. |
| Swamp HTTP client: list and get videos, delete a video, list channels, subscribe, add to queue, list queue, start download, rescan, refresh. | Not an MCP server. Mutations are not confirm-gated. Narrower than the 79 actions here. |
Tests
npm run ci typechecks, lints, runs Vitest, builds, and checks that src/operations.ts matches the inventory.
Vitest covers the write-guard matrix for every write (omit, false, true, writes off, writes on, TRUE, 1), preview versus confirmed, unknown fields, spec coverage, pagination query forwarding, HTTP 401, 403, 404, 422, and 429 mapping, and leak regressions for the API token and for cookie and password fields. 401, 422, and 429 are simulated. See LIVE-CHECK.md for which codes a real v0.6.0 process returned.
Live check
unset DATABASE_URL
/workspace/tools/tubearchivist/start.sh
cd /workspace/connectors/tubearchivist
export TUBEARCHIVIST_URL=http://127.0.0.1:18765
export TUBEARCHIVIST_TOKEN_FILE=/workspace/tools/tubearchivist/runtime/api.token
unset TUBEARCHIVIST_TOKEN
npm run live-check
/workspace/tools/tubearchivist/stop.shstart.sh is idempotent. It binds Elasticsearch 127.0.0.1:19200 (transport 19300), Redis 127.0.0.1:16379, and Tube Archivist 127.0.0.1:18765. It does not use Docker and does not print passwords or the token. stop.sh closes those ports.
Available Tools
14 toolsta_channelADestructive
List, search, subscribe, update, and delete channels. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: list (GET /api/channel/), subscribe (POST /api/channel/), search (GET /api/channel/search/), get (GET /api/channel/{channel_id}/), update (POST /api/channel/{channel_id}/), delete (DELETE /api/channel/{channel_id}/), aggs (GET /api/channel/{channel_id}/aggs/), nav (GET /api/channel/{channel_id}/nav/).
Inputs: action (required), q, page, filter, +3 more.
ta_configADestructive
Application settings and YouTube cookie status. Cookie values are redacted. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: get (GET /api/appsettings/config/), update (POST /api/appsettings/config/), cookie_status (GET /api/appsettings/cookie/), cookie_validate (POST /api/appsettings/cookie/), cookie_import (PUT /api/appsettings/cookie/), cookie_revoke (DELETE /api/appsettings/cookie/).
Inputs: action (required), confirm, document.
ta_downloadADestructive
Read and change the download queue, including add, priority start, and delete. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: list (GET /api/download/), add (POST /api/download/), bulk_update (PATCH /api/download/), bulk_delete (DELETE /api/download/), aggs (GET /api/download/aggs/), get (GET /api/download/{video_id}/), update (POST /api/download/{video_id}/), delete (DELETE /api/download/{video_id}/).
Inputs: action (required), q, flat, page, +9 more.
ta_libraryADestructive
Reindex progress and watched-state changes for a video, channel, or playlist. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: refresh_status (GET /api/refresh/), refresh (POST /api/refresh/), watched (POST /api/watched/).
Inputs: action (required), id, type, confirm, +2 more.
ta_maintenanceADestructive
Snapshots, zip backups, filesystem rescan, and manual import. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: snapshots (GET /api/appsettings/snapshot/), snapshot_create (POST /api/appsettings/snapshot/), snapshot_get (GET /api/appsettings/snapshot/{snapshot_id}/), snapshot_restore (POST /api/appsettings/snapshot/{snapshot_id}/), snapshot_delete (DELETE /api/appsettings/snapshot/{snapshot_id}/), backups (GET /api/appsettings/backup/), backup_create (POST /api/appsettings/backup/), backup_get (GET /api/appsettings/backup/{filename}/), backup_restore (POST /api/appsettings/backup/{filename}/), backup_delete (DELETE /api/appsettings/backup/{filename}/), rescan (POST /api/appsettings/rescan-filesystem/), import (POST /api/appsettings/manual-import/).
Inputs: action (required), confirm, document, filename, +1 more.
ta_mediaARead-only
Subtitle tracks as WebVTT text. Binary media is not exposed. Reads only. Actions: subtitle (GET /media/subtitle/{channel_id}/{video_id}.{lang}.vtt).
Inputs: action (required), lang, video_id, channel_id.
ta_notifyADestructive
Read and edit webhook URLs stored on scheduled tasks. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: list (GET /api/task/notification/), add (POST /api/task/notification/), remove (DELETE /api/task/notification/).
Inputs: action (required), confirm, document.
ta_playlistADestructive
List, subscribe, update, and delete playlists, including custom playlists. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: list (GET /api/playlist/), subscribe (POST /api/playlist/), create_custom (POST /api/playlist/custom/), update_custom (POST /api/playlist/custom/{playlist_id}/), get (GET /api/playlist/{playlist_id}/), update (POST /api/playlist/{playlist_id}/), delete (DELETE /api/playlist/{playlist_id}/).
Inputs: action (required), page, type, channel, +5 more.
ta_searchARead-only
Full-text search across videos, channels, and playlists. Reads only. Actions: search (GET /api/search/).
Inputs: action (required), query.
ta_statsCRead-only
Library, download, and watch statistics. Reads only. Actions: video (GET /api/stats/video/), channel (GET /api/stats/channel/), playlist (GET /api/stats/playlist/), download (GET /api/stats/download/), watch (GET /api/stats/watch/), download_history (GET /api/stats/downloadhist/), biggest_channels (GET /api/stats/biggestchannels/).
Inputs: action (required), order.
ta_systemARead-only
Ping, health, and in-app notification messages. Reads only. Actions: ping (GET /api/ping/), health (GET /api/health/), notifications (GET /api/notification/).
Inputs: action (required), filter.
ta_taskADestructive
Read task results, start or stop tasks, and manage schedules. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: results (GET /api/task/by-name/), results_by_name (GET /api/task/by-name/{task_name}/), start (POST /api/task/by-name/{task_name}/), get (GET /api/task/by-id/{task_id}/), command (POST /api/task/by-id/{task_id}/), schedules (GET /api/task/schedule/), schedule_get (GET /api/task/schedule/{task_name}/), schedule_upsert (POST /api/task/schedule/{task_name}/), schedule_delete (DELETE /api/task/schedule/{task_name}/).
Inputs: action (required), confirm, task_id, document, +1 more.
ta_userADestructive
The account behind the token and per-user view preferences. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: account (GET /api/user/account/), me (GET /api/user/me/), update (POST /api/user/me/).
Inputs: action (required), confirm, document.
ta_videoADestructive
List, read, delete, navigate, and comment on archived videos, plus playback progress. Writes run only when confirm is true and TUBEARCHIVIST_ALLOW_WRITES=true. Otherwise the call is a dry-run and no HTTP write is sent. Actions: list (GET /api/video/), get (GET /api/video/{video_id}/), delete (DELETE /api/video/{video_id}/), nav (GET /api/video/{video_id}/nav/), similar (GET /api/video/{video_id}/similar/), comments (GET /api/video/{video_id}/comment/), progress_set (POST /api/video/{video_id}/progress/), progress_clear (DELETE /api/video/{video_id}/progress/).
Inputs: action (required), page, sort, type, +8 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool is scoped to a distinct resource domain (channel, video, playlist, download, task, config, etc.), so most selections are unambiguous, and the embedded action lists plus HTTP endpoints further disambiguate. A few edges blur: ta_system.notifications (in-app) versus ta_notify (webhook URLs on scheduled tasks), and ta_library.refresh (reindex) versus ta_maintenance.rescan versus ta_task.start, could be confused by an agent.
All 14 tools follow an identical ta_<resource> pattern with singular resource nouns, and sub-operations are consistently expressed as named actions inside each tool. No camelCase/snake_case mixing or ad-hoc verb prefixes anywhere.
14 tools is squarely in the well-scoped range and maps one-to-one onto TubeArchivist's resource domains rather than exposing each of the ~70 REST actions as a separate tool. The grouping keeps the surface navigable without omitting functionality.
Coverage is unusually thorough: full CRUD for channels, playlists (including custom), downloads, tasks and schedules, snapshots/backups, config/cookies, user prefs, plus stats, search, subtitles and watched-state. Minor gaps remain — no operation to add an individual video to a custom playlist, comments are read-only, and there is no search-suggestion/autocomplete action.
Maintenance
Related MCP Connectors
Search Bluesky posts and feeds; read profiles, threads, and trends. STDIO or Streamable HTTP.
Fetch the transcript of any YouTube video (plain text or timestamped segments, in any available caption language), search YouTube for videos and channels, list a channel's uploads, Shorts, playlists and community posts, search inside one channel, and list every video in a playlist. Hosted Streamable HTTP server from getyoutubetranscript.com; sign in with OAuth or an API key. Credit-based: one credit per successful call.
Download YouTube videos and clips as MP4 or MP3/AAC, and look up video metadata.
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables searching YouTube Music and managing playlists through read and confirmation-gated write tools over STDIO. Supports identity checks, song search, playlist listing/retrieval, and previewed playlist creation, track addition, and exact track removal.MIT
- AlicenseAqualityCmaintenanceEnables managing a self-hosted media library through its HTTP API, with scoped toolsets, confirm-gated writes, dry-run previews, and read caching. Supports libraries, items, collections, playlists, podcasts, sessions, stats, tags, genres, and administrative operations.13131 npmMIT
- AlicenseNot gradedqualityCmaintenanceConnects MCP clients to a self-hosted Seafile server through the seahub HTTP API, exposing libraries, files, search, sharing, and optional admin operations over stdio or Streamable HTTP. It defaults to read-focused tools and gates writes behind confirmation, with token redaction and dry-run previews.9 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables interaction with self-hosted Miniflux instances through the HTTP API, covering feeds, categories, entries, enclosures, icons, OPML, users, and API keys. Write operations are confirm-gated with dry-run previews and secret redaction.6 npmMIT