mcp-invidious

MCP Invidious

Model Context Protocol server that provides YouTube search capabilities through Invidious instances.

Features

• Search videos, channels, and playlists with filtering by date, duration, and sort order
• Video details including title, description, views, likes, duration, and keywords
• Channel details with subscriber count, description, and metadata
• Video comments with reply counts and sorting options
• Trending videos by category and region
• Dual transport: stdio for CLI agents, HTTP for remote connections

Available Tools

Tool	Description
search_videos	Search YouTube videos with optional filters (sort_by, date, duration)
search_channels	Search YouTube channels
search_playlists	Search YouTube playlists
video_details	Get detailed information about a specific video
channel_details	Get detailed information about a specific channel
video_comments	Get comments for a video
trending	Get trending videos by type and region

Quick Start

Prerequisites

• Rust 1.93+
• An Invidious instance URL

Build and Run

cargo build --release

# Run with stdio transport (default)
INVIDIOUS_URL=https://vid.puffyan.us cargo run --release

# Run with HTTP transport
INVIDIOUS_URL=https://vid.puffyan.us MCP_TRANSPORT=http cargo run --release

Configuration

Variable	Default	Required	Description
INVIDIOUS_URL	—	Yes	Invidious instance base URL
MCP_TRANSPORT	stdio	No	Transport mode: stdio or http
MCP_HOST	0.0.0.0	No	HTTP bind address
MCP_PORT	3005	No	HTTP bind port
INVIDIOUS_LANG	es	No	Default search language (ISO 639-1)
INVIDIOUS_INSECURE	false	No	Disable TLS certificate verification (true/1)
INVIDIOUS_ENABLED_TOOLS	(all)	No	Comma-separated list of enabled tools, or all

Docker

Build the image:

podman build -t mcp-invidious:latest .

Run with Podman:

podman run -e INVIDIOUS_URL=https://vid.puffyan.us -p 3005:3005 mcp-invidious:latest

Or use the provided systemd container unit:

# Edit mcp-invidious.container with your INVIDIOUS_URL, then:
systemctl --user enable --now mcp-invidious.container

Architecture

src/
├── main.rs          # Entry: env → config → transport (stdio/http) → boot
├── config.rs        # AppConfig from env vars with defaults
├── handler.rs       # ServerHandler impl (tool dispatch via tool_box!)
├── error.rs         # thiserror-based error types
├── invidious.rs     # reqwest client + Invidious API response types
└── tools.rs         # Tools via #[mcp_tool] macro + formatting helpers

Development

cargo build
cargo run
cargo test
cargo clippy -- -D warnings
cargo fmt

License

MIT