quicktube-mcp 1.0.0__tar.gz

quicktube_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AW3 Technology, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quicktube_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,165 @@
+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

quicktube_mcp-1.0.0/README.md

@@ -0,0 +1,132 @@
+# 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

quicktube_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+# setuptools 77+ understands the SPDX `license` string and `license-files`.
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quicktube-mcp"
+dynamic = ["version"]
+description = "MCP server for QuickTube (quicktube.ai): YouTube transcripts, AI summaries, quizzes and fact-checks for AI agents"
+readme = {file = "README.md", content-type = "text/markdown"}
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "AW3 Technology, Inc.", email = "will.schulz@aw3.tech"}
+]
+keywords = ["youtube", "transcript", "mcp", "model-context-protocol", "ai", "video", "summary", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10"
+dependencies = [
+    # mcp 1.8-1.21 import a private pydantic helper that pydantic 2.12
+    # removed, and they don't cap pydantic, so with a current pydantic they
+    # crash on import (checked against 2.14). 1.22 is the first that works.
+    # mcp 2.x removed `mcp.server.fastmcp` (renamed to MCPServer); without the
+    # upper bound, `uvx quicktube-mcp` resolves mcp 2.x and crashes on import.
+    "mcp>=1.22,<2",
+    "httpx>=0.27,<1",
+]
+
+[project.scripts]
+quicktube-mcp = "quicktube_mcp.server:main"
+
+[project.urls]
+Homepage = "https://quicktube.ai"
+Documentation = "https://quicktube.ai/api-docs"
+"MCP setup" = "https://quicktube.ai/api-docs#mcp-server"
+"API keys" = "https://quicktube.ai/settings?tab=api-keys"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["quicktube_mcp*"]
+
+[tool.setuptools.dynamic]
+# Single source of truth: quicktube_mcp/__init__.py
+version = {attr = "quicktube_mcp.__version__"}
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

quicktube_mcp-1.0.0/quicktube_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""QuickTube MCP Server - Expose QuickTube API as MCP tools for AI agents."""
+
+__version__ = "1.0.0"