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.

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:

"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)

NotebookLM — Notebooks (5 tools)

NotebookLM — Artifacts (4 tools)

Pipeline (1 tool)

Environment Variables

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