[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

# TubeMCP

MCP server that lets AI agents search YouTube and fetch transcripts. Zero config — just install and go.

**What is MCP?** [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants like Claude call external tools. TubeMCP gives your AI agent the ability to search YouTube and read any video's transcript — useful for summarization, Q&A, research, and content analysis.

## Prerequisites

- **Python 3.10+** — [download](https://www.python.org/downloads/)

## Installation

```bash
pip install tubemcp
```

or

```bash
uv tool install tubemcp
```

Then add it to your client:

**Claude Code:**

```bash
claude mcp add tubemcp -- tubemcp
```

**Claude Desktop** — add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tubemcp": {
      "command": "tubemcp"
    }
  }
}
```

**Cursor** — add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "tubemcp": {
      "command": "tubemcp"
    }
  }
}
```

**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "tubemcp": {
      "command": "tubemcp"
    }
  }
}
```

## What you get

### `youtube_get_transcript`

Fetch the English transcript and metadata for any YouTube video.

**Input:** A YouTube URL or video ID in any of these formats:

- `https://www.youtube.com/watch?v=VIDEO_ID`
- `https://youtu.be/VIDEO_ID`
- `https://www.youtube.com/embed/VIDEO_ID`
- `https://www.youtube.com/v/VIDEO_ID`
- `VIDEO_ID` (bare 11-character ID)

**Returns:**

- `video_id` — the video ID
- `title` — video title
- `channel_name` — channel name
- `thumbnail_url` — thumbnail URL
- `duration_seconds` — video duration
- `publish_date` — publish date
- `transcript` — full transcript text
- `from_cache` — whether the result was served from cache

### `youtube_search`

Search YouTube with multiple queries for broader coverage. Results are deduplicated by video ID. Returns metadata only — no transcripts.

**Input:**

- `queries` (`list[str]`) — search queries to run. Use 2–3 from different angles for best results.
- `max_results_per_query` (`int`, default `3`) — max results returned per query.

**Returns** a list of results, each containing:

- `video_id` — the video ID
- `title` — video title
- `channel_name` — channel name
- `url` — video URL
- `duration_seconds` — video duration

## Caching

Transcripts are cached locally in `~/.tubemcp/cache.db` (SQLite). Subsequent requests for the same video are served instantly from cache.

## Troubleshooting

### `spawn uvx ENOENT`

This means your MCP client can't find the `uvx` command. Three fixes:

1. **uv not installed** — Install it: https://docs.astral.sh/uv/getting-started/installation/
2. **uv not on PATH** — Use the full path to `uvx` in your config (find yours with `which uvx`):
   ```json
   "command": "/Users/you/.local/bin/uvx"
   ```
3. **Switch to pip** — Skip uv entirely. Install with `pip install tubemcp` and use `"command": "tubemcp"` in your config (see [pip installation](#pip) above).

**Verify uv is working:**

```bash
uvx --version
```

## Development

```bash
git clone https://github.com/BlockBenny/tubemcp.git
cd tubemcp
pip install -e ".[dev]"
pytest
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT