Metadata-Version: 2.4
Name: quicktube-mcp
Version: 1.0.0
Summary: MCP server for QuickTube (quicktube.ai): YouTube transcripts, AI summaries, quizzes and fact-checks for AI agents
Author-email: "AW3 Technology, Inc." <will.schulz@aw3.tech>
License-Expression: MIT
Project-URL: Homepage, https://quicktube.ai
Project-URL: Documentation, https://quicktube.ai/api-docs
Project-URL: MCP setup, https://quicktube.ai/api-docs#mcp-server
Project-URL: API keys, https://quicktube.ai/settings?tab=api-keys
Keywords: youtube,transcript,mcp,model-context-protocol,ai,video,summary,claude
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.22
Requires-Dist: httpx<1,>=0.27
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# QuickTube MCP Server

<!-- mcp-name: ai.quicktube/quicktube-mcp -->

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for [QuickTube](https://quicktube.ai). It lets AI agents such as Claude Code, Claude Desktop and Cursor fetch YouTube transcripts, summarize videos, find the key moments, generate quizzes, fact-check claims and more.

- Website: https://quicktube.ai
- API and MCP docs: https://quicktube.ai/api-docs
- Get an API key: https://quicktube.ai/settings?tab=api-keys

## Tools

| Tool | Description | Credits |
|------|-------------|---------|
| `get_transcript` | Fetch a YouTube video transcript (paged for long videos) | 1 per call |
| `summarize_video` | Generate an AI summary | 5 |
| `get_best_sections` | Identify key moments and highlights | 5 |
| `detect_characters` | Detect speakers and people | 3 |
| `chat_with_video` | Ask questions about the video's content | 1/msg |
| `generate_quiz` | Create a comprehension quiz | 5 |
| `fact_check_video` | Fact-check claims (web-grounded) | 5 |
| `get_bias_score` | Analyze political/ideological bias | 5 |
| `neutralize_bias` | Rewrite biased language neutrally | 5 |
| `get_video_metadata` | Get video title, stats, duration | 0 |
| `search_videos` | Search YouTube | 0 |
| `get_video_comments` | Get video comments | 0 |
| `get_related_videos` | Find related videos | 0 |
| `list_sessions` | List saved analysis sessions | 0 |
| `get_session` | Get a saved session | 0 |
| `save_session` | Save an analysis for later | 0 |
| `delete_session` | Delete a saved session | 0 |
| `get_credit_balance` | Check your credit balance | 0 |
| `batch_process_videos` | Analyze up to 20 videos at once | per video: transcript 1, summary 5, sections 5 |

## Setup

### 1. Get an API key

Create an API key at [quicktube.ai/settings?tab=api-keys](https://quicktube.ai/settings?tab=api-keys). Each tool needs a scope on the key:

| Scope | Tools | In a new key by default |
|-------|-------|-------------------------|
| `transcript` | `get_transcript` | yes |
| `ai` | `summarize_video`, `get_best_sections`, `detect_characters`, `chat_with_video`, `fact_check_video`, `get_bias_score`, `neutralize_bias` | yes |
| `batch` | `batch_process_videos` | yes |
| `sessions:read` | `list_sessions`, `get_session` | no |
| `sessions:write` | `save_session`, `delete_session` | no |
| `billing:read` | `get_credit_balance` | no |

`generate_quiz` and the YouTube data tools (`get_video_metadata`, `search_videos`, `get_video_comments`, `get_related_videos`) need no particular scope. Keys created on the settings page get the default scopes only, so the session and balance tools return 403 with them.

### 2. Add the server to your MCP client

The quickest route is [`uvx`](https://docs.astral.sh/uv/), which downloads and runs the server without a separate install step.

**Claude Code**

```bash
claude mcp add quicktube --env QUICKTUBE_API_KEY=qt_your_api_key_here -- uvx quicktube-mcp
```

**Claude Desktop, Cursor and other clients** (`claude_desktop_config.json`, `.cursor/mcp.json`, `.mcp.json`, ...):

```json
{
  "mcpServers": {
    "quicktube": {
      "command": "uvx",
      "args": ["quicktube-mcp"],
      "env": {
        "QUICKTUBE_API_KEY": "qt_your_api_key_here"
      }
    }
  }
}
```

**With pip instead of uvx**

```bash
pip install quicktube-mcp
```

Then use `"command": "quicktube-mcp"` (no `args`) in the config above.

### Environment variables

| Variable | Required | Default |
|----------|----------|---------|
| `QUICKTUBE_API_KEY` | yes | none |
| `QUICKTUBE_BASE_URL` | no | `https://quicktube.ai` |
| `QUICKTUBE_TIMEOUT` | no | `120` (seconds; batch calls always get at least 600) |

The server starts without `QUICKTUBE_API_KEY` so clients can list its tools, but every tool call fails until the key is set. `QUICKTUBE_BASE_URL` may be given with or without a trailing `/api`.

### Long transcripts

`get_transcript` returns at most `max_chars` characters (80,000 by default, roughly 20k tokens) so a three-hour podcast doesn't flood the agent's context. When the result has `"truncated": true`, call it again with `offset` set to the returned `next_offset`. Each call costs a credit, so for a whole long video `summarize_video`, `get_best_sections` or `chat_with_video` are usually the better tools. `get_session`, `list_sessions` and `batch_process_videos` likewise leave out the timestamped transcript entries and cap the transcript text.

### Errors

API errors come back to the agent as tool errors with the status and the server's reason, for example `QuickTube API error 402 (Payment Required): Insufficient credits (needs 5 credits, balance 2). Buy credits at https://quicktube.ai/pricing`, or a 429 with the `Retry-After` delay.

## Running it directly

```bash
quicktube-mcp              # MCP over stdio (what MCP clients expect)
quicktube-mcp --help
quicktube-mcp --version
quicktube-mcp --transport streamable-http   # local HTTP transport
```

## Example prompts

- "Get me the transcript of this YouTube video and summarize it."
- "What are the key moments in this podcast episode?"
- "Fact-check the claims made in this news video."
- "Generate a quiz from this educational video."
- "Is this video politically biased? Analyze it."
- "Process these 5 videos and give me summaries of each."

## Development

```bash
pip install -e '.[test]'
pytest
quicktube-mcp --help
```

## License

MIT
