Vidcap Mcp Server

VidCap YouTube API - MCP Server

This project provides a Model Context Protocol (MCP) server that acts as a proxy to the VidCap YouTube API, allowing AI assistants to easily access YouTube video data and functionalities. It also serves as a boilerplate for building custom MCP servers.

• Github
• NPM

Table of Contents

• [VidCap YouTube API](#vidcap-youtube-api)
• [MCP Client Integration](#mcp-client-integration)
• [Claude Desktop Configuration](#claude-desktop-configuration)
• [Claude Code Integration](#claude-code-integration)
• [Security Best Practices](#security-best-practices)
• [Advanced Configuration](#advanced-configuration)
• [Troubleshooting](#troubleshooting)
• [Available MCP Tools](#available-mcp-tools)
• [Source Code Overview](#source-code-overview)

VidCap YouTube API

This server also proxies requests to the VidCap YouTube API, providing convenient access to YouTube video data and functionalities. You will need a VIDCAP_API_KEY set in your environment variables.

Endpoints are available under the /api/v1/youtube/ path:

• GET /info
• Description: Get and save YouTube video information.
• Query Parameters:
• url (string, required): YouTube video URL.
• cache (boolean, optional, default: true): Whether to cache video info.
• GET /media
• Description: Get available media formats for a YouTube video.
• Query Parameters:
• url (string, required): YouTube video URL.
• GET /caption
• Description: Get video captions/transcript.
• Query Parameters:
• url (string, required): YouTube video URL.
• locale (string, optional, default: 'en'): Language code for captions.
• model (string, optional): AI model for processing.
• ext (enum, optional): File extension for captions (json3, srv1, srv2, srv3, ttml, vtt).
• GET /summary
• Description: Get AI-generated summary of video content.
• Query Parameters:
• url (string, required): YouTube video URL.
• locale (string, optional, default: 'en'): Target language code for summary.
• model (string, optional): AI model for summarization.
• screenshot (string, optional, default: '0'): '1' to enable auto-screenshots for summary parts.
• cache (boolean, optional): Whether to use cached results.
• GET /screenshot
• Description: Get screenshot from video at specific timestamp.
• Query Parameters:
• url (string, required): YouTube video URL.
• second (string, optional, default: '0'): Timestamp in seconds or YouTube time format.
• GET /screenshot-multiple
• Description: Get multiple screenshots from video at different timestamps.
• Query Parameters:
• url (string, required): YouTube video URL.
• second (array of strings, optional, default: ['0']): Array of timestamps in seconds.
• GET /comments
• Description: Get YouTube video comments with optional pagination and replies.
• Query Parameters:
• url (string, optional): YouTube video URL.
• videoId (string, optional): YouTube video ID. Note: Either url or videoId is required.
• order (enum, optional, default: 'time'): Sort order for comments ('time', 'relevance').
• format (enum, optional, default: 'plainText'): Format of comment text ('plainText', 'html').
• pageToken (string, optional): Pagination token for retrieving next page of comments.
• includeReplies (boolean, optional, default: false): Include comment replies.
• hl (string, optional, default: 'en'): Language code for comments.
• GET /search
• Description: Search YouTube videos with comprehensive filtering and pagination support.
• Query Parameters:
• query (string, required): Search query for YouTube videos.
• maxResults (number, optional, default: 10): Maximum number of results to return (1-50).
• order (enum, optional, default: 'relevance'): Sort order for search results ('date', 'rating', 'relevance', 'title', 'videoCount', 'viewCount').
• publishedAfter (string, optional): Filter videos published after this date (ISO 8601 format).
• publishedBefore (string, optional): Filter videos published before this date (ISO 8601 format).
• videoDuration (enum, optional, default: 'any'): Filter by video duration ('short', 'medium', 'long', 'any').
• videoDefinition (enum, optional, default: 'any'): Filter by video quality ('high', 'standard', 'any').
• pageToken (string, optional): Pagination token for retrieving next page of results.

Supported Transports

• [x] "stdio" transport - Default transport for CLI usage
• [x] "Streamable HTTP" transport - For web-based clients
• [ ] Implement auth ("Authorization" headers with Bearer )
• [ ] ~~"sse" transport~~ (Deprecated)
• [ ] Write tests

How to use

CLI

This server can be extended with CLI commands. Currently, the primary interaction is via the HTTP API endpoints for the VidCap YouTube API.

Example of running the server (which exposes the API):

npm run dev:server:http

Examples of running the CLI commands:

# Get YouTube video information
npm run dev:cli -- youtube getInfo --url "" --cache true

# Get available media formats for a YouTube video
npm run dev:cli -- youtube getMedia --url ""

# Get video captions/transcript
npm run dev:cli -- youtube getCaption --url "" --locale "en" --model ""

# Get AI-generated summary of video content
npm run dev:cli -- youtube getSummary --url "" --locale "en" --model "" --screenshot "0" --cache true

# Get screenshot from video at specific timestamp
npm run dev:cli -- youtube getScreenshot --url "" --second "30"

# Get multiple screenshots from video at different timestamps
npm run dev:cli -- youtube getScreenshotMultiple --url "" --seconds 10 30 60

# Get YouTube video comments with pagination and replies
npm run dev:cli -- youtube getComments --url "" --includeReplies --order relevance

# Get YouTube video comments using videoId with specific page
npm run dev:cli -- youtube getComments --videoId "dQw4w9WgXcQ" --pageToken ""

# Note: YouTube search functionality is currently available as an MCP tool only
# Use the youtube_search tool through your MCP-compatible AI assistant

MCP Client Integration

This server provides 8 YouTube-related MCP tools that can be integrated with any MCP-compatible AI assistant. The tools include video information retrieval, media format discovery, caption/transcript extraction, AI-powered summarization, screenshot capture, comment analysis, and comprehensive video search.

Quick Setup

1. Get VidCap API Key

1. Visit vidcap.zuey.me to obtain your API key
2. Set the API key in your environment or MCP client configuration

2. Configure Your MCP Client

The server is available on NPM and can be run directly with npx - no installation required!

Choose your configuration method based on your AI assistant:

Claude Desktop Configuration

Automatic Configuration (Recommended)

Claude Desktop provides a user-friendly interface for MCP server configuration:

1. Open Claude Desktop Settings

• Click the settings icon (⚙️) in Claude Desktop
• Navigate to the "Developer" tab
• Click "Edit Config" to open the configuration file

1. Add VidCap MCP Server

Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "vidcap-youtube-api": {
      "command": "npx",
      "args": ["vidcap-mcp-server"],
      "env": {
        "VIDCAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Manual Configuration

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "vidcap-youtube-api": {
      "command": "npx",
      "args": ["vidcap-mcp-server"],
      "env": {
        "VIDCAP_API_KEY": "your_api_key_here",
        "DEBUG": "false"
      }
    }
  }
}

Troubleshooting Claude Desktop

• Configuration Issues: Verify JSON syntax using a JSON validator
• Server Not Starting: Check logs at ~/Library/Logs/Claude/mcp.log (macOS)
• Permission Errors: Ensure Node.js and npm are properly installed
• Test Manually: Run npx vidcap-mcp-server in terminal to verify server functionality

Claude Code Integration

Claude Code supports MCP servers with multiple configuration methods:

Method 1: CLI Configuration (Recommended)

Use Claude Code's built-in MCP management:

# Add the VidCap MCP server
claude mcp add --transport stdio vidcap-youtube-api npx vidcap-mcp-server

# Set environment variables
claude mcp env set vidcap-youtube-api VIDCAP_API_KEY=your_api_key_here

Method 2: Project-Level Configuration

Create a .mcp.json file in your project root for team-shared configuration:

{
  "mcpServers": {
    "vidcap-youtube-api": {
      "command": "npx",
      "args": ["vidcap-mcp-server"],
      "transport": "stdio",
      "env": {
        "VIDCAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Method 3: User-Level Configuration

For cross-project accessibility, configure in your user settings:

{
  "mcpServers": {
    "vidcap-youtube-api": {
      "command": "npx",
      "args": ["vidcap-mcp-server"],
      "transportType": "stdio",
      "scope": "user",
      "env": {
        "VIDCAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code Features

• Resource References: Use @vidcap-youtube-api to reference server capabilities
• Slash Commands: Access tools via /youtube commands (if supported)
• Environment Variables: Supports secure credential management
• Scope Management: Control server accessibility at project, user, or local levels

Import from Claude Desktop

If you have existing Claude Desktop configuration:

# Import configuration from Claude Desktop
claude mcp import-from-claude-desktop

Quick Reference

Essential Commands

# Install and test server
npx vidcap-mcp-server

# Claude Code: Add server
claude mcp add --transport stdio vidcap-youtube-api npx vidcap-mcp-server

# Claude Code: Set API key
claude mcp env set vidcap-youtube-api VIDCAP_API_KEY=your_key

# Claude Code: List servers
claude mcp list

# Claude Code: Remove server
claude mcp remove vidcap-youtube-api

Minimal Configurations

Claude Desktop (Basic):

{
  "mcpServers": {
    "vidcap": {
      "command": "npx",
      "args": ["vidcap-mcp-server"],
      "env": { "VIDCAP_API_KEY": "your_key" }
    }
  }
}

Claude Code (Project .mcp.json):

{
  "mcpServers": {
    "vidcap": {
      "command": "npx",
      "args": ["vidcap-mcp-server"],
      "env": { "VIDCAP_API_KEY": "your_key" }
    }
  }
}

Cline (VS Code Extension)

Add to your Cline MCP configuration:

{
  "mcpServers": {
    "vidcap-youtube-api": {
      "command": "npx",
      "args": ["vidcap-mcp-server"],
      "env": {
        "VIDCAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor Configuration

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "vidcap-youtube-api": {
      "command": "npx",
      "args": ["vidcap-mcp-server"],
      "transportType": "stdio",
      "env": {
        "VIDCAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

HTTP Transport Configuration

For web-based clients or remote access:

{
  "mcpServers": {
    "vidcap-youtube-api": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "env": {
        "VIDCAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

HTTP Server Environment Variables:

• MCP_HTTP_HOST: Host to bind to (default: 127.0.0.1)
• MCP_HTTP_PORT: Port to listen on (default: 8080)
• MCP_HTTP_PATH: Endpoint path (default: /mcp)

Start HTTP Server:

# Using npx
npx vidcap-mcp-server --http

# Or with custom configuration
MCP_HTTP_PORT=3000 npx vidcap-mcp-server --http

# Using local development server
npm run start:server:http

Alternative Installation Methods

NPX (Recommended)

The configurations above use npx which automatically downloads and runs the latest version without installation.

Global Installation

For better performance or offline usage:

# Install globally
npm install -g vidcap-mcp-server

# Use in MCP config (replace npx with direct command)
{
  "mcpServers": {
    "vidcap-youtube-api": {
      "command": "vidcap-mcp-server",
      "env": {
        "VIDCAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Local Development

For development or customization:

# Clone and build locally
git clone https://github.com/mrgoonie/vidcap-mcp-server.git
cd vidcap-mcp-server
npm install
npm run build

# Use local build in MCP config
{
  "mcpServers": {
    "vidcap-youtube-api": {
      "command": "node",
      "args": ["/path/to/vidcap-mcp-server/dist/index.js"],
      "env": {
        "VIDCAP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available MCP Tools

Once configured, your AI assistant will have access to these tools:

• youtube_getInfo: Get video metadata (title, description, duration, etc.)
• youtube_getMedia: List available video/audio formats and quality options
• youtube_getCaption: Extract captions/transcripts with timing information
• youtube_getSummary: Generate AI-powered video content summaries
• youtube_getScreenshot: Capture screenshots at specific timestamps
• youtube_getScreenshotMultiple: Batch capture multiple screenshots
• youtube_getComments: Retrieve video comments with pagination and replies
• youtube_search: Search YouTube videos with advanced filtering options (query, date range, duration, quality, sorting)

YouTube Search Tool Features

The youtube_search tool provides powerful video discovery capabilities with multiple filtering options:

Basic Search:

• Search by keywords, phrases, or topics
• Configurable result limits (1-50 videos per request)
• Pagination support for browsing large result sets

Advanced Filtering:

• Sort Options: relevance, date, rating, title, videoCount, viewCount
• Duration Filters: short (20 min), or any
• Quality Filters: high definition, standard definition, or any quality
• Date Range: Filter videos published within specific date ranges
• Pagination: Navigate through search results with page tokens

Example Use Cases:

• Find recent tutorials: "Python tutorial" + order: "date" + videoDuration: "medium"
• Discover popular content: "machine learning" + order: "viewCount" + maxResults: 25
• Research within timeframe: "AI developments" + publishedAfter: "2024-01-01"
• Quality-focused search: "4K nature documentary" + videoDefinition: "high"

Response Data: Each search result includes video metadata such as title, description, channel information, thumbnails, publication date, and engagement metrics (views, likes when available).

Configuration Options

API Key Sources (Priority Order)

1. Environment Variables: VIDCAP_API_KEY
2. MCP Client Config: env.VIDCAP_API_KEY in server config
3. Global MCP Config: ~/.mcp/configs.json
4. HTTP Query Parameter: ?api_key=your_key (HTTP transport only)

Debug Mode

Enable detailed logging for troubleshooting:

{
  "env": {
    "V

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mrgoonie](https://github.com/mrgoonie)
- **Source:** [mrgoonie/vidcap-mcp-server](https://github.com/mrgoonie/vidcap-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.