Skip to main content
Glama
mcp-research-pipeline

mcp-research-pipeline

by rubayatkhan

mcp-research-pipeline

MCP server that unifies YouTube transcripts, YouTube search, and Google NotebookLM into a research pipeline for Claude Desktop and any MCP client.

What It Does

  • Extract YouTube transcripts (free, no API key needed)

  • Search YouTube for videos, channels, and playlists (via TranscriptAPI.com)

  • Create NotebookLM notebooks, add sources, ask questions, and generate deliverables (podcasts, quizzes, reports, etc.)

  • One-shot research pipeline: search → create notebook → add sources → ask — in a single tool call

NotebookLM acts as a free RAG system — Google pays for the analysis tokens. This MCP server lets Claude Desktop interact with it programmatically.

Related MCP server: claude-youtube-transcript

Quick Start

Prerequisites

  • Python 3.10+

  • uv (recommended) or pip

Step 1: Clone and install

git clone https://github.com/rubayatkhan/mcp-research-pipeline.git
cd mcp-research-pipeline
uv sync

Step 2: Install Playwright browser

NotebookLM requires a Chromium browser for authentication. This is a one-time setup:

uv run python -m playwright install chromium

Note: playwright is not a standalone CLI command — it's bundled inside the project's virtual environment. Always run it with uv run python -m playwright, not just playwright.

Step 3: Authenticate with NotebookLM (optional)

uv run notebooklm login

This opens a browser window for Google sign-in. Your credentials are saved at ~/.notebooklm/storage_state.json and persist across server restarts.

Skip this step if you only want YouTube transcript/search tools. NotebookLM tools will return a helpful error message telling you to authenticate.

Step 4: Get a TranscriptAPI key (optional)

Sign up at transcriptapi.com to get an API key. You get 100 free credits.

Skip this step if you only need get_transcript (which is free and keyless). The search, channel, and playlist tools require this key.

Step 5: Configure Claude Desktop

Add to your Claude Desktop config:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A — Direct venv script (recommended, avoids path issues):

{
  "mcpServers": {
    "research-pipeline": {
      "command": "/absolute/path/to/mcp-research-pipeline/.venv/bin/mcp-research-pipeline",
      "env": {
        "TRANSCRIPT_API_KEY": "your-key-here"
      }
    }
  }
}

Replace /absolute/path/to/mcp-research-pipeline with your actual clone location. Leave TRANSCRIPT_API_KEY empty or omit the env block if you don't have a key yet.

Option B — Using uv run (only if your path has no spaces):

{
  "mcpServers": {
    "research-pipeline": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/mcp-research-pipeline",
        "python", "-m", "mcp_research_pipeline"
      ],
      "env": {
        "TRANSCRIPT_API_KEY": "your-key-here"
      }
    }
  }
}

Warning: Option B fails if your path contains spaces (e.g., iCloud Drive, OneDrive, Google Drive). Use Option A instead.

Step 6: Restart Claude Desktop

Fully quit Claude Desktop (Cmd+Q / Ctrl+Q) and reopen it. The research-pipeline server should appear in your MCP tools.

Troubleshooting

"Server disconnected" in Claude Desktop

Check the server log at ~/Library/Logs/Claude/mcp-server-research-pipeline.log (macOS). Common causes:

Error

Fix

No module named mcp_research_pipeline

Your path has spaces. Switch to Option A (direct venv script).

No module named playwright

Run uv run python -m playwright install chromium in the project directory.

command not found: playwright

Don't use playwright directly. Use uv run python -m playwright install chromium.

Server starts then immediately disconnects

NotebookLM auth may have expired. Run uv run notebooklm login again.

"NotebookLM is not connected"

Run uv run notebooklm login in the project directory. This opens a browser for Google authentication.

"TRANSCRIPT_API_KEY" errors

The get_transcript tool works without any API key. Only search_youtube, get_channel_latest, get_channel_videos, and get_playlist_videos need a TranscriptAPI.com key.

Paths with spaces (iCloud, OneDrive, Google Drive)

If your project lives in a path with spaces (like ~/Library/Mobile Documents/com~apple~CloudDocs/), the uv run --directory approach will fail. Two options:

  1. Use Option A (direct venv script path) — this always works.

  2. Create a symlink to a path without spaces:

    ln -sf "/path/with spaces/mcp-research-pipeline" ~/mcp-research-pipeline

    Then point Claude Desktop at ~/mcp-research-pipeline/.venv/bin/mcp-research-pipeline.

Tools (15 total)

YouTube (5 tools)

Tool

Cost

Description

get_transcript

Free

Fetch transcript from a YouTube URL or video ID

search_youtube

1 credit

Search YouTube for videos or channels

get_channel_latest

Free

Get 15 most recent videos from a channel

get_channel_videos

1 credit/page

Paginated list of all channel videos

get_playlist_videos

1 credit/page

Paginated list of playlist videos

NotebookLM — Notebooks (5 tools)

Tool

Description

create_notebook

Create a new NotebookLM notebook

list_notebooks

List all notebooks

add_source

Add a URL, YouTube video, or text to a notebook

list_sources

List sources in a notebook

ask_notebook

Ask a question against notebook sources (RAG)

NotebookLM — Artifacts (4 tools)

Tool

Description

generate_artifact

Generate audio, video, quiz, flashcards, report, mind_map, infographic, slide_deck, or data_table

list_artifacts

List all artifacts in a notebook

check_artifact_status

Poll generation status

download_artifact

Download a completed artifact

Pipeline (1 tool)

Tool

Description

research_topic

End-to-end: search YouTube → create notebook → add sources → ask question

Environment Variables

Variable

Required

Description

TRANSCRIPT_API_KEY

No

TranscriptAPI.com API key (enables YouTube search tools)

NOTEBOOKLM_STORAGE_PATH

No

Custom path to NotebookLM auth (default: ~/.notebooklm/storage_state.json)

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/

# Run server locally (stdio mode)
uv run python -m mcp_research_pipeline

Architecture

The server uses three design patterns:

  • Facade Pattern: 15 MCP tools presenting a unified interface over three different APIs

  • Adapter Pattern: clients/ layer wraps each third-party library behind a common async interface

  • Lifespan Management: FastMCP lifespan hook creates expensive clients once at startup, tears them down on shutdown

server.py (FastMCP + lifespan)
├── clients/
│   ├── youtube_transcript.py  → youtube-transcript-api (sync→async)
│   ├── transcript_api.py      → TranscriptAPI.com REST (httpx)
│   └── notebooklm.py          → notebooklm-py (async)
├── tools/
│   ├── youtube.py     (5 tools)
│   ├── notebook.py    (5 tools)
│   ├── artifacts.py   (4 tools)
│   └── pipeline.py    (1 tool)
└── utils/
    ├── youtube_url.py  (URL parsing)
    └── errors.py       (error translation)

License

MIT

Available Tools

15 tools
add_sourceB

Add a source to a NotebookLM notebook.

Inputs: value (required), notebook_id (required), source_type (required), wait. Returns: result

ask_notebookA

Ask a question against the sources in a NotebookLM notebook.

NotebookLM uses your sources as context (RAG) and provides referenced answers. This is powered by Google's infrastructure.

Inputs: question (required), notebook_id (required), source_ids. Returns: result

check_artifact_statusB

Check the generation status of a NotebookLM artifact.

Inputs: task_id (required), notebook_id (required). Returns: result

create_notebookB

Create a new NotebookLM notebook.

Inputs: name (required). Returns: result

download_artifactA

Download a completed NotebookLM artifact to a local file.

Inputs: notebook_id (required), output_path (required), artifact_type (required), artifact_id. Returns: result

generate_artifactA

Generate a NotebookLM artifact from notebook sources.

Supported artifact types: audio, video, quiz, flashcards, report, mind_map, infographic, slide_deck, data_table.

Inputs: notebook_id (required), artifact_type (required), wait, source_ids, +1 more. Returns: result

get_channel_latestB

Get the 15 most recent videos from a YouTube channel. FREE — no credits.

Inputs: channel (required). Returns: result

get_channel_videosA

Paginated list of all videos from a YouTube channel. Costs 1 credit/page.

Inputs: channel, continuation. Returns: result

get_playlist_videosB

Paginated list of videos in a YouTube playlist. Costs 1 credit/page.

Inputs: playlist, continuation. Returns: result

get_transcriptB

Fetch the transcript of a YouTube video.

Inputs: video (required), languages, preserve_formatting. Returns: result

list_artifactsA

List all artifacts in a NotebookLM notebook.

Inputs: notebook_id (required). Returns: result

list_notebooksA

List all NotebookLM notebooks.

Returns: JSON array of notebooks with notebook_id, name, created_at, source_count.

Inputs: no named parameters. Returns: result

list_sourcesA

List all sources in a NotebookLM notebook.

Inputs: notebook_id (required). Returns: result

research_topicA

End-to-end research pipeline: search YouTube, create a NotebookLM notebook, add video sources, and optionally ask a question.

This tool orchestrates the full workflow:

  1. Search YouTube for videos matching the query

  2. Create a new NotebookLM notebook

  3. Add each video as a YouTube source

  4. Optionally ask a question against all sources

Requires both TRANSCRIPT_API_KEY (for search) and NotebookLM login.

Inputs: query (required), question, max_videos, notebook_name. Returns: result

search_youtubeA

Search YouTube for videos or channels. Costs 1 TranscriptAPI credit.

Inputs: query (required), limit, result_type. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 15 tools

    Disambiguation4/5

    Tools are mostly distinct by resource and action, with clear separation between YouTube retrieval and NotebookLM management. The main ambiguity is between get_channel_latest and get_channel_videos, though descriptions clarify the convenience vs. paginated distinction. research_topic overlaps with the individual steps but is clearly positioned as an orchestrator.

    Naming Consistency4/5

    All tool names use snake_case and generally follow a verb_noun pattern, which keeps the set predictable. Minor inconsistencies like get_channel_latest omitting a noun and mixing list_/get_ for similar operations prevent a perfect score.

    Tool Count4/5

    At 15 tools, the server sits at the upper bound of a well-scoped set, but the count is justified by covering two integrated domains: YouTube retrieval and NotebookLM management. research_topic and get_channel_latest add some redundancy but still serve useful convenience purposes.

    Completeness4/5

    The core research workflow is covered end-to-end: search YouTube, create a notebook, add sources, ask questions, and generate/download artifacts. Missing delete/update operations for notebooks, sources, and artifacts are notable gaps but not critical for the stated pipeline purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients such as Claude and Copilot to turn YouTube videos into a persistent, compounding wiki by extracting knowledge from transcripts and scene-change vision analysis. Lets clients run agentic search over that compiled knowledge, answering questions with source citations and awareness of what the wiki does not yet cover.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Turns YouTube videos into a persistent, cross-referenced wiki by extracting transcripts and describing scene-change frames with vision models. Enables MCP clients like Claude and Copilot to search and reason over this compounding knowledge base without needing an API key.
      -