youtube-mcp

# YouTube MCP Server

<!-- mcp-name: com.hasdata/youtube -->

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client four read-only YouTube tools. Search YouTube, read video and channel data, and pull transcripts, with no Google Cloud project and no YouTube Data API key.

```
https://mcp.hasdata.com/api/mcp?apis=youtube
```

[![Glama score](https://glama.ai/mcp/servers/HasData/youtube-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HasData/youtube-mcp)
[![tool contract](https://github.com/HasData/youtube-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/youtube-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-4-10b981?style=flat-square)](#tools)
[![npm](https://img.shields.io/npm/v/@hasdata/youtube-mcp?style=flat-square&logo=npm&label=npm&color=cb3837)](https://www.npmjs.com/package/@hasdata/youtube-mcp)
[![PyPI](https://img.shields.io/pypi/v/hasdata-youtube-mcp?style=flat-square&logo=pypi&logoColor=white&label=PyPI&color=3775a9)](https://pypi.org/project/hasdata-youtube-mcp/)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client that speaks streamable HTTP with custom headers. A HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=youtube-mcp), free to create. Nothing else. This is a remote server, so the simplest path is a URL and a header, with no container to run and no Google account anywhere in the flow. A stdio-only client can use the `@hasdata/youtube-mcp` (npm) or `hasdata-youtube-mcp` (PyPI) launcher instead.

## Quick start

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

| Field | Value |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=youtube` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http youtube "https://mcp.hasdata.com/api/mcp?apis=youtube" \
  --header "x-api-key: HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=youtube` and sign in.

For the config-file route, Claude Desktop loads only local (stdio) servers, so it reaches a remote server through a stdio launcher. The `@hasdata/youtube-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@hasdata/youtube-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

Python instead of Node? Swap the launcher for the PyPI package, which `uvx` runs without a manual install:

```json
{
  "mcpServers": {
    "youtube": {
      "command": "uvx",
      "args": ["hasdata-youtube-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "youtube": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cline</b></summary>

```json
{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "youtube": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Codex CLI</b></summary>

`~/.codex/config.toml`:

```toml
[mcp_servers.youtube]
url = "https://mcp.hasdata.com/api/mcp?apis=youtube"

[mcp_servers.youtube.headers]
"x-api-key" = "HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Gemini CLI</b></summary>

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "youtube": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

## Example prompts

Prompts, not code. Paste one in and the agent picks the tool itself. Each is annotated with the calls it takes, because in MCP the model decides how many calls to make and every successful call costs 10 credits.

> Find the ten most viewed videos about the Model Context Protocol from the last month, then pull the transcript of the top one and give me the three claims it makes about tool calling.

*Two calls, 20 credits.*

> Take the channel @GoogleDevelopers. List the tabs it publishes, then summarize the last five uploads and tell me which topics repeat.

*Two calls, 20 credits. Reading a tab you have not seen takes a second call, because the tab list arrives inside the first response.*

> Take this video id, dQw4w9WgXcQ. Get its stats, then check which of its related videos come from the same channel.

*One call, 10 credits. Related videos ride along in the same response.*

> Search YouTube for "web scraping tutorial", sorted by upload date, videos under four minutes only, and give me the chapter titles of each result that has them.

*One call, 10 credits.*

> Pull the German transcript of this video if one exists, and tell me which languages it is available in.

*One call, 10 credits.*

Search takes YouTube's own filter tokens, and an agent narrows by duration, upload date and content type without post-processing. Transcripts arrive with the list of available language tracks, which lets the agent pick one without guessing.

Paging costs a call each time. A research prompt that searches, pages twice, then pulls three transcripts is six calls and 60 credits. The trial goes further on narrow questions than on open-ended crawls.

## Tools

Four tools, all read-only. Samples below are trimmed from real calls, and the numbers in them move as YouTube updates. Read them as shapes. Each tool name links to its endpoint reference, which carries the full field list.

The samples are the payload, not the whole response. A `tools/call` result carries one text block, and that text is itself JSON holding `url`, `status`, `text` and `json`, with the scraped data under `json`. From a raw JSON-RPC response the path is `result.content[0].text`, parsed, then `.json`. A chat client unwraps that for you and code talking to the endpoint directly does not.

### Get YouTube search results

[`hasdata_youtube_search_getYoutubeSearchResults`](https://docs.hasdata.com/apis/youtube/search?utm_source=github&utm_medium=syndication&utm_campaign=youtube-mcp)

Searches YouTube and returns the whole results page, split by result type.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `q` | string | yes | Free-text query, exactly as a user would type it |
| `sortBy` | string | | `relevance` by default, plus `date`, `views`, `rating` and `popularity` |
| `date` | string | | Upload window relative to now |
| `length` | string | | Duration bucket, for example `under4` |
| `videoType` | string | | Restrict to one content type |
| `filters__` | array | | Feature flags, combinable |
| `sp` | string | | Raw YouTube `sp` token copied from a search URL. Overrides `sortBy`, `date`, `videoType`, `length` and `filters__` with no warning, so leave those empty when you pass a token |
| `paginationToken` | string | | The `pagination.nextPageToken` from the previous response |
| `gl` / `hl` / `deviceType` | string | | Two-letter country and language codes, and device |

A results page is split across `videoResults`, `shortsResults`, `inlineShortsResults`, `playlistResults`, `channelResults` and `shelves`, with paid placements in `adsResults` and `sponsoredResults`. Which blocks appear depends on the query, and a block with nothing to report is absent, not empty. Test for the key before iterating. `searchInformation` carries the total and `pagination.nextPageToken` is what you feed back as `paginationToken`. Ads never mix into the organic arrays, though there are two of them to skip.

```json
{
  "positionOnPage": 1,
  "videoId": "GuTcle5edjk",
  "title": "you need to learn MCP RIGHT NOW!! (Model Context Protocol)",
  "viewsOriginal": "1.6M views",
  "views": 1653824,
  "length": "38:40",
  "publishedDate": "11 months ago",
  "extensions": ["4K"],
  "chapters": [
    { "title": "Intro", "time": "0:00" },
    { "title": "Problem: LLMs Suck at Accessing Code", "time": "0:40" }
  ],
  "channel": { "name": "NetworkChuck", "verif