{
  "markdown": "<div align=\"center\">\n\n<img src=\"assets/logo-small.webp\" alt=\"Transcriptor MCP\" width=\"120\" />\n\n# 🎬 Now your AI assistant can watch videos!\n\n**Connect one server. Then ask Claude, ChatGPT or etc about a video:** the transcript, the chapters, the metadata, or a single frame. It works with 11 platforms, not only YouTube.\n\n[![Website](https://img.shields.io/badge/Website-transcriptor--mcp.org-C15F3C)](https://transcriptor-mcp.org)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-transcriptor--mcp-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=transcriptor)\n[![Docker](https://img.shields.io/badge/Docker-artsamsonov/transcriptor--mcp-2496ED?logo=docker&logoColor=white)](https://hub.docker.com/r/artsamsonov/transcriptor-mcp)\n[![MCP Apps](https://img.shields.io/badge/MCP%20Apps-4%20interactive%20widgets-8A63D2)](#-widgets)\n[![License](https://img.shields.io/github/license/samson-art/transcriptor-mcp)](LICENSE)\n\n**[Connect](#-connect-in-30-seconds) · [What to ask](#-what-you-can-ask) · [Widgets](#-widgets) · [Platforms](#-platforms) · [Self-host](#-self-host)**\n\n</div>\n\n---\n\n## ⚡ Connect in 30 seconds\n\nThe hosted endpoint is:\n\n```text\nhttps://transcriptor.gateway.mcpal.io/mcp\n```\n\n### 🖱️ One click\n\n[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=transcriptor&config=eyJ1cmwiOiJodHRwczovL3RyYW5zY3JpcHRvci5nYXRld2F5Lm1jcGFsLmlvL21jcCJ9)\n[![Install in VS Code](https://img.shields.io/badge/Install%20in-VS%20Code-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=transcriptor&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Ftranscriptor.gateway.mcpal.io%2Fmcp%22%7D)\n[![Add to LM Studio](https://img.shields.io/badge/Add%20to-LM%20Studio-4B5563?style=for-the-badge)](https://lmstudio.ai/install-mcp?name=transcriptor&config=eyJ1cmwiOiJodHRwczovL3RyYW5zY3JpcHRvci5nYXRld2F5Lm1jcGFsLmlvL21jcCJ9)\n\n### ⌨️ One command, for Claude Code\n\n```bash\nclaude mcp add --transport http transcriptor https://transcriptor.gateway.mcpal.io/mcp\n```\n\nThen run `/mcp` and approve the sign-in in the browser. After this, `claude mcp list` shows `✔ Connected`.\n\n### 🧭 No terminal\n\n| Client | What to do |\n| --- | --- |\n| **Claude** (web and desktop) | Open [Settings → Customize → Connectors](https://claude.ai/settings/connectors). Select **Add** → **Add custom connector**, paste `https://transcriptor.gateway.mcpal.io/mcp`, then select **Add**. |\n| **ChatGPT** | Open [Settings → **Security and login**](https://chatgpt.com/#settings) and turn on **Developer mode**. Then open Plugins, select **+**, and paste `https://transcriptor.gateway.mcpal.io/mcp`. |\n| **Codex** | Add the block below to `~/.codex/config.toml`, then run `codex mcp login transcriptor`. The CLI, the IDE extension and the ChatGPT desktop app share this file. |\n\n```toml\n[mcp_servers.transcriptor]\nurl = \"https://transcriptor.gateway.mcpal.io/mcp\"\nauth = \"oauth\"\n```\n\n> **Note:** ChatGPT developer mode is available on the web, for paid plans. Some releases show this control as Settings → Apps & Connectors → Advanced.\n>\n> **Note:** `codex mcp add` registers stdio servers only, so a hosted server goes into `config.toml`. See the [Codex MCP docs](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).\n\n### 🧩 Any other MCP client\n\nIf your client is not in the list above, add the server with this configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"transcriptor\": {\n      \"url\": \"https://transcriptor.gateway.mcpal.io/mcp\"\n    }\n  }\n}\n```\n\nIf you want to run the server yourself, read [Self-host](#-self-host). The tools are the same and you need no account.\n\n---\n\n## 🧰 What you can ask\n\n| Ask for this | Tool |\n| --- | --- |\n| *\"Summarize this video for me\"* | `get_transcript` |\n| *\"Give me the subtitles as an SRT file\"* | `get_raw_subtitles` |\n| *\"Is there a German track for this video?\"* | `get_available_subtitles` |\n| *\"Who published this and how many views?\"* | `get_video_info` |\n| *\"Go to the part about pricing\"* | `get_video_chapters` |\n| *\"Show me the screen at 4:12\"* | `get_video_frame` |\n| *\"Get transcripts for the first 5 videos in this playlist\"* | `get_playlist_transcripts` |\n| *\"Find recent videos about X\"* | `search_videos` (YouTube) |\n\nLong transcripts come in parts. Each response gives a cursor for the next part, so no text is lost.\n\n<details>\n<summary><b>Full tool reference</b> (input and structured response)</summary>\n\nEach tool that takes a video accepts `url`. This is a link from a [supported platform](#-platforms) or a plain YouTube ID. Each tool returns `content` (text for the chat) and `structuredContent` (typed JSON for your code).\n\n#### `get_transcript`\n\nClean plain text, without timestamps, HTML, or speaker names. The tool finds the type and the language for you.\n\nResponse: `videoId`, `type`, `lang`, `text`, `is_truncated`, `total_length`, `start_offset`, `end_offset`. When more text is available, the response also has `next_cursor`.\n\n#### `get_raw_subtitles`\n\nRaw SRT or VTT content, in parts.\n\nInput:\n\n- `type` — `official` or `auto`\n- `lang` — a language code\n- `response_limit` — default `50000`, minimum `1000`, maximum `200000`\n- `next_cursor` — the cursor of the previous response\n\nResponse: the fields of `get_transcript`, plus `format` (`srt` or `vtt`) and `content`.\n\n#### `get_available_subtitles`\n\nResponse: `official` and `auto`. Each field is a sorted list of language codes. Use this tool first, then give `type` and `lang` to the tools above.\n\n#### `get_video_info`\n\nExtended metadata from yt-dlp:\n\n- identity — `videoId`, `title`, `description`, `webpageUrl`\n- author — `uploader`, `uploaderId`, `channel`, `channelId`, `channelUrl`\n- numbers — `duration`, `uploadDate`, `viewCount`, `likeCount`, `commentCount`\n- classification — `tags`, `categories`, `liveStatus`, `isLive`, `wasLive`, `availability`\n- images — `thumbnail` and `thumbnails`\n\n#### `get_video_chapters`\n\nResponse: `chapters`. Each item has `startTime`, `endTime`, and `title`. When the video has no chapters, the list is empty.\n\n#### `get_video_frame`\n\nInput:\n\n- `timecode` — `\"MM:SS\"` or `\"HH:MM:SS.mmm\"`\n- `seconds` — an alternative to `timecode`. Give one of the two, not both\n- `format` — `jpeg` (default) or `png`\n- `width` — default `1280`, maximum `1920`, never larger than the source\n- `quality` — `2` to `31`, for jpeg only\n\nResponse: an image block, plus `timestampSeconds`, `timestamp`, `mimeType`, `sizeBytes`, and `width`. This tool needs `ffmpeg`. The Docker image includes it.\n\n#### `get_playlist_transcripts`\n\nInput:\n\n- `url` — a playlist URL, or a watch URL with `list=`\n- `type`, `lang`, `format` — the same as `get_raw_subtitles`\n- `playlistItems` — a yt-dlp `-I` value such as `1:5`, `1,3,7`, or `-1`\n- `maxItems` — the maximum number of videos\n\nResponse: `results`. Each item has `videoId` and `text`.\n\n#### `search_videos`\n\nInput:\n\n- `query` — the search text\n- `limit` — default 10, maximum 50\n- `offset` — the number of results to skip\n- `uploadDateFilter` — `hour`, `today`, `week`, `month`, or `year`\n- `response_format` — `json` (default) or `markdown`\n\nResponse: `results`. Each item has `videoId`, `title`, `url`, `duration`, `uploader`, `viewCount`, and `thumbnail`.\n\n</details>\n\n---\n\n## 📺 Widgets\n\nFour tools have an interactive interface: `get_transcript`, `get_video_info`, `get_video_frame`, and `search_videos`. Clients that support [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) and the ChatGPT Apps SDK show this interface in the chat. Other clients get the same data as text and JSON.\n\n<table>\n  <tr>\n    <td width=\"50%\" valign=\"top\">\n      <img src=\"assets/widget-search.webp\" alt=\"The search_videos widget: a carousel of result cards with thumbnails, durations, and view counts\" />\n      <p align=\"center\"><sub><code>search_videos</code> · <i>\"model context protocol MCP server production\"</i></sub></p>\n    </td>\n    <td width=\"50%\" valign=\"top\">\n      <img src=\"assets/widget-video-frame.webp\" alt=\"The get_video_frame widget: one captured frame with step controls and a timecode field\" />\n      <p align=\"center\"><sub><code>get_video_frame</code> · an architecture slide at 3:30</sub></p>\n    </td>\n  </tr>\n  <tr>\n    <td width=\"50%\" valign=\"top\">\n      <img src=\"assets/widget-transcript.webp\" alt=\"The get_transcript widget: a video card above a searchable list of timed captions\" />\n      <p align=\"center\"><sub><code>get_transcript</code> · a 3-minute MCP explainer, official captions</sub></p>\n    </td>\n    <td width=\"50%\" valign=\"top\">\n      <img src=\"assets/widget-video-info.webp\" alt=\"The get_video_info widget: thumbnail, channel, views, likes, description, and a subtitle language picker\" />\n      <p align=\"center\"><sub><code>get_video_info</code> · channel, views, likes, and 169 caption languages</sub></p>\n    </td>\n  </tr>\n</table>\n\n---\n\n## 🌍 Platforms\n\n**YouTube · Twitter/X · Instagram · TikTok · Twitch · Vimeo · Facebook · Bilibili · VK · Dailymotion · Reddit**\n\nEach tool that takes a video accepts a link from these 11 platforms. The tool `search_videos` works with YouTube only, through yt-dlp `ytsearch`.\n\nThe server does not download video or audio files for you. It returns text, metadata, and single frames.\n\n---\n\n## 🐳 Self-host\n\nThe tools are the same as on the hosted endpoint. You need no account.\n\nRun the server with Docker. The image serves Streamable HTTP on port 4200:\n\n```bash\ndocker run --rm -p 4200:4200 artsamsonov/transcriptor-mcp:latest\n```\n\nThen point your client at `http://localhost:4200/mcp`.\n\nFor stdio, give the image an explicit command:\n\n```bash\ndocker run --rm -i artsamsonov/transcriptor-mcp:latest npm run start:mcp\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"transcriptor\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"artsamsonov/transcriptor-mcp:latest\", \"npm\", \"run\", \"start:mcp\"]\n    }\n  }\n}\n```\n\nThe server starts with no environment variables. Each variable below is optional.\n\n| Variable | Default | Function |\n| --- | --- | --- |\n| `MCP_PORT` and `MCP_HOST` | `4200` and `0.0.0.0` | The HTTP listener |\n| `COOKIES_FILE_PATH` | — | A Netscape cookies file for videos that need an account. See [cookies.example.txt](cookies.example.txt) |\n| `WHISPER_MODE` | `off` | Set `local` or `api` to transcribe the audio when a video has no subtitles. Then set `WHISPER_BASE_URL` or `WHISPER_API_KEY` |\n| `CACHE_MODE` | `off` | Set `redis` and `CACHE_REDIS_URL` to cache subtitles and metadata |\n| `YT_DLP_*` | — | Timeouts, proxy, and JS runtimes. See [.env.example](.env.example) |\n\nThe same port serves `GET /health` and `GET /metrics`. The metrics are in Prometheus format and include the `mcp_*` counters.\n\n<details>\n<summary><b>Transport, REST API, and development</b></summary>\n\n**Transport.** The server accepts `POST /mcp` only. `GET` and `DELETE` return `405`. The server is stateless and sends no `Mcp-Session-Id`.\n\nThe Node process does not check bearer tokens. Put a reverse proxy or a gateway in front of it for authentication and TLS. The hosted endpoint works this way.\n\n**REST API.** A second image gives the same extraction over plain HTTP:\n\n```bash\ndocker run --rm -p 3000:3000 artsamsonov/transcriptor-mcp-api:latest\n```\n\nThe Swagger interface is at `http://localhost:3000/docs`. For a full stack with the API and the MCP server, read [docker-compose.example.yml](docker-compose.example.yml).\n\n**Development.**\n\n```bash\nnpm ci\nnpm run build\nnpm run dev:mcp        # stdio, hot reload\nnpm run dev:mcp:http   # Streamable HTTP, hot reload\nnpm test\n```\n\nYou need Node.js 20 or later, and `yt-dlp` in your PATH. Frame capture also needs `ffmpeg`. Other scripts: `lint`, `type-check`, `format`, `test:coverage`, `test:e2e:api`, and `test:e2e:mcp`.\n\n**Releases.** The version comes from `package.json` at runtime, through [src/version.ts](src/version.ts). Change this version, move the `[Unreleased]` entries of the changelog into the new version, then push a `v*` tag. CI builds both images and publishes the [MCP Registry](https://registry.modelcontextprotocol.io) entry from [server.json](server.json).\n\n**Layout.** `src/mcp.ts` (stdio entry), `src/mcp-http.ts` (Streamable HTTP), `src/mcp-core.ts` (tools, prompts, widgets), `src/youtube.ts` (yt-dlp), `src/whisper.ts`, `src/cache.ts`, `src/index.ts` (REST API), `load/` (k6), and `src/e2e/` (Docker smoke tests).\n\n</details>\n\n---\n\n## 🤝 Contributing\n\nPull requests are welcome. Fork the repository, make a branch, and make sure that `npm test` and `npm run lint` pass. Then open a pull request.\n\n## ⚖️ Legal\n\nThe hosted endpoint at `transcriptor.gateway.mcpal.io` is governed by the [Terms of Service](legal/TERMS_OF_SERVICE.md) and the [Privacy Policy](legal/PRIVACY_POLICY.md).\n\nA server you host yourself is not covered by those documents. It is governed by the MIT License only.\n\n## 📄 License\n\nMIT © 2026 samson-art. Read [LICENSE](LICENSE).\n\n## 💬 Support\n\n[Issues](https://github.com/samson-art/transcriptor-mcp/issues) · [GitHub profile](https://github.com/samson-art) · [LinkedIn](https://www.linkedin.com/in/artem-samsonov-284a66105/)\n",
  "bytes": 13160,
  "sha": "12ffceb770c6812a911ed9528a8d6a210ed8899adb0febf77faf10ee25d2c7ba",
  "repo_slug": "samson-art/transcriptor-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_samson_art_transcriptor_mcp_c2fff182/readme"
}