# MCP YouTube Transcribe

> An AI-powered MCP server for fetching/generating YouTube video transcripts.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jackhp-mcp-youtube-transcribe`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JackHP](https://agentstack.voostack.com/s/jackhp)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JackHP](https://github.com/JackHP)
- **Source:** https://github.com/JackHP/MCP-YouTube-Transcribe

## Install

```sh
agentstack add mcp-jackhp-mcp-youtube-transcribe
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP-YouTube-Transcribe

[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/uv)

An MCP server that provides a tool to fetch transcripts from YouTube videos. It first attempts to
retrieve a pre-existing, official transcript. If one is not available, it downloads the video's audio and uses OpenAI's
Whisper model for local AI-powered transcription.

This project is designed to be a simple, self-contained tool that can be easily integrated into any system capable of
communicating with an MCP server.

## Features

* **YouTube Video Search:** Finds the most relevant YouTube video based on a text query.
* **Official Transcript Priority:** Intelligently fetches manually created or auto-generated YouTube transcripts first
  for speed and accuracy.
* **Fast AI-Powered Transcription:** Uses whisper.cpp (if available) for blazing fast transcription. Falls back to OpenAI's Python Whisper
  `tiny` model if whisper.cpp is not installed.
* **MCP Server Interface:** Exposes the transcription functionality as a simple tool (`get_youtube_transcript`) via the
  lightweight model context protocol.

## Requirements

* Python 3.12+
* **[uv](https://github.com/astral-sh/uv):** A fast Python package installer and resolver. You will need to [install
  `uv`](https://github.com/astral-sh/uv#installation) on your system first.
* **[FFmpeg](https://ffmpeg.org/download.html):** Must be installed and available in your system's PATH. Required for audio processing.
* **[whisper.cpp](https://github.com/ggerganov/whisper.cpp)** *(Highly recommended)*: MCP-YouTube-Transcribe will **first** try to use whisper.cpp for lightning-fast local transcription and only fall back to Python Whisper if the executable is not found.
  - macOS: `brew install whisper-cpp`
  - Linux: Build from source following the [whisper.cpp installation guide](https://github.com/ggerganov/whisper.cpp#build)
  - Windows: Build from source or grab a pre-built binary from the [releases page](https://github.com/ggerganov/whisper.cpp/releases)

  After installation, make sure the `whisper-cli` (or `whisper-cpp` on older versions) command is in your PATH.

  Finally, download a Whisper model. The **tiny** model offers the best speed-to-quality ratio for most use-cases:

  ```bash
  mkdir -p models
  curl -L -o models/ggml-tiny.bin \
       https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin
  ```

  Place additional models in the same `models/` folder if you wish to experiment.

## Installation with `uv`

Using `uv` is recommended as it's extremely fast and handles both environment creation and package installation
seamlessly.

1. **Clone the repository:**
   ```bash
   git clone https://github.com//YouTubeTranscriber.git
   cd YouTubeTranscriber
   ```

2. **Create and activate a virtual environment:**
   This command creates a `.venv` folder in your project directory and activates it. `uv` will automatically use this
   environment for all subsequent commands.
   ```bash
   uv venv
   ```

3. **Install the project and its dependencies:**
   This command reads the `pyproject.toml` file and installs all required libraries into the virtual environment.
   ```bash
   uv sync
   ```

## Usage

### Running the MCP Server

Once installed, you can start the server by running the `mcp_server.py` script. The server will listen for JSON-RPC
requests on `stdin` and send responses to `stdout`.

```bash 
python mcp_server.py
``` 

The server will log its activity to a file named `mcp_server.log` in the project's root directory.

## Connecting to Gemini CLI on Windows

You can connect this MCP server to the Google Gemini CLI to use the function as a native tool directly from your
terminal. These instructions are for a **Windows** environment.

### Step 1: Create a Startup Script `run_server.bat`

The Gemini CLI needs a single, reliable command to start your server. A batch script is the perfect way to handle this
on Windows, as it ensures the correct virtual environment and Python interpreter are used.

1. Create a new file named in the root of your project directory. `run_server.bat`
2. Copy and paste the following content into the file:

``` batch
    @echo off
    REM This ensures the script's directory is the current directory
    cd /d "%~dp0"
    
    REM --- IMPORTANT ---
    REM Replace the path below with the ABSOLUTE path to your project's venv python.exe
    set PYTHON_EXE="C:\Users\jackp\.pyenv\pyenv-win\versions\3.12.10\python3.12.exe"
    
    echo --- Starting MCP Server using %PYTHON_EXE% ---
    %PYTHON_EXE% mcp_server.py
    
    pause
```

_This script activates the virtual environment in your project and then runs the server, ensuring all the correct
dependencies are available.`.venv`_

### Step 2: Configure the Gemini CLI

Now, you need to tell the Gemini CLI how to find and run your new server.

1. Locate your Gemini CLI `config.json` file. On Windows, this is typically found at:
   `C:\Users\\.gemini\config.json`
2. Open the `config.json` file in a text editor. Add the following entry to the `mcpServers` object. If `mcpServers`
   doesn't exist, create it as shown below.

``` json
    {
      "mcpServers": {
        "MCP-YouTube-Transcribe": {
          "command": "C:\\Windows\\System32\\cmd.exe",
          "args": [
            "/c",
            "\\run_server.bat"
          ],
          "cwd": ""
        }
      }
    }
```

3. **Crucially, you must replace both instances of ``** with the full, absolute path to where you
   cloned the `YouTubeTranscriber` repository.

**Example:** If your project is located at `C:\dev\YouTubeTranscriber`, the entry would look like this:

``` json
    {
      "mcpServers": {
        "MCP-YouTube-Transcribe": {
          "command": "C:\\Windows\\System32\\cmd.exe",
          "args": [
            "/c",
            "C:\\dev\\YouTubeTranscriber\\run_server.bat"
          ],
          "cwd": "C:\\dev\\YouTubeTranscriber"
        }
      }
    }
```

**Note**: JSON requires backslashes to be escaped, so you must use double backslashes (`\\`) in your paths.

### Step 3: Verify the Connection

After saving the `config.json` file, you can verify that Gemini CLI recognizes and can use your new tool.

Run Gemini CLI and press ctrl+t

You should see `MCP-YouTube-Transcribe` listed as an available tool.

## Connecting to Gemini CLI on Mac/Unix

You can also connect this MCP server to the Google Gemini CLI on Mac or other Unix-like systems. The process is similar to Windows but uses a shell script instead of a batch file.

### Step 1: Prepare the Startup Script

The repository already includes a `run_server.sh` script. Just make it executable:

```bash
chmod +x run_server.sh
```

### Step 2: Configure the Gemini CLI

1. Locate your Gemini CLI `config.json` file. On Mac/Unix systems, this is typically found at:
   `~/.gemini/config.json`

2. Open the `config.json` file in a text editor. Add the following entry to the `mcpServers` object. If `mcpServers`
   doesn't exist, create it as shown below:

```json
{
  "mcpServers": {
    "MCP-YouTube-Transcribe": {
      "command": "/path/to/your/project/run_server.sh",
      "cwd": "/path/to/your/project"
    }
  }
}
```

3. **Replace both instances of `/path/to/your/project`** with the absolute path to where you cloned the repository.

**Example:** If your project is located at `/Users/username/MCP-YouTube-Transcribe`, the entry would look like this:

```json
{
  "mcpServers": {
    "MCP-YouTube-Transcribe": {
      "command": "/Users/username/MCP-YouTube-Transcribe/run_server.sh",
      "cwd": "/Users/username/MCP-YouTube-Transcribe"
    }
  }
}
```

### Step 3: Verify the Connection

After saving the `config.json` file, you can verify that Gemini CLI recognizes and can use your new tool.

Run Gemini CLI and press ctrl+t

You should see `MCP-YouTube-Transcribe` listed as an available tool.

### MCP Client Example

You can interact with the server using any client that supports the MCP protocol over stdio. The server exposes one
primary tool: `get_youtube_transcript`.

Here is an example of a `call_tool` request to get a transcript for the query "What is an API? by MuleSoft".

**Request:**

```json 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "call_tool",
  "params": {
    "name": "get_youtube_transcript",
    "arguments": {
      "query": "What is an API? by MuleSoft",
      "force_whisper": false
    }
  }
}
``` 

* `query`: The search term for the YouTube video.
* `force_whisper`: (Optional) A boolean that, if `true`, skips the check for an official transcript and generates one
  directly with Whisper. Defaults to `false`.

## Testing

This project includes a test suite to verify its functionality.

* **Core Function Test (`simple.py`):** This script tests the server's handler functions directly without needing to run
  a separate server process. It's the quickest way to check if the core logic is working.
  ```bash
  python simple.py
  ```

* **Full Server Test (`test_mcp.py`):** This script starts the MCP server as a subprocess and sends it live JSON-RPC
  requests, providing an end-to-end test of the server's functionality.
  ```bash
  python test_mcp.py
  ```

## Configuration

* **Logging:** Server activity is logged to `mcp_server.log`.
* **Audio Cache:** When Whisper is used, downloaded audio files are temporarily stored in `testing/audio_cache/`. You
  may wish to change this path in `youtube_tool.py` for a production environment.

## Contributing

Contributions are welcome! If you'd like to improve the YouTube Transcriber, please feel free to fork the repository and
submit a pull request.

Please read our `CONTRIBUTING.md` for details on our code of conduct and the process for submitting pull requests to us.

## License

This project is licensed under the MIT License - see the `LICENSE` file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JackHP](https://github.com/JackHP)
- **Source:** [JackHP/MCP-YouTube-Transcribe](https://github.com/JackHP/MCP-YouTube-Transcribe)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jackhp-mcp-youtube-transcribe
- Seller: https://agentstack.voostack.com/s/jackhp
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.