Stophy

MCP Server

Use Stophy as hosted MCP tools for YouTube search, transcripts, comments, channels, playlists, suggestions, and credits.

Copy MarkdownOpen

Stophy exposes YouTube search, transcripts, comments, channels, playlists, suggestions, and credits as MCP tools.

You can connect in two ways:

• Hosted HTTP MCP: connect directly to Stophy's hosted Streamable HTTP endpoint.

• Local npm server: run @stophy/mcp locally with your API key in the environment.

Hosted HTTP MCP

Recommended: header-based auth

Connect to the base hosted MCP endpoint and pass your API key in a standard Authorization header:

https://api.stophy.dev/v1/mcp

Authorization: Bearer $STOPHY_API_KEY

This keeps your key out of the URL. Use this method whenever your MCP client can send custom request headers.

Fallback: path-based auth (compatibility only)

For MCP clients that cannot send custom headers, Stophy also accepts the API key in the URL path:

https://api.stophy.dev/v1/mcp/st_YOUR_API_KEY

This puts your API key directly in the URL, where it can leak through browser history, Referer headers, screenshots, and server, proxy, or CDN access logs. Only use path-based auth when header auth is impossible. Prefer a key reserved for this purpose and rotate it regularly.

Local npm MCP server

env STOPHY_API_KEY=st_YOUR_API_KEY npx -y @stophy/mcp

Get your API key from stophy.dev/dashboard.

Tools

Tool What it does stophy_search_videos Search YouTube by keyword with filters for type, date, duration, and sort order stophy_get_video Get details, transcript, comments, replies, or live chat for a video URL stophy_get_channel Browse a channel's videos, Shorts, playlists, or about page stophy_get_playlist Fetch videos in a playlist with metadata stophy_get_suggestions Get autocomplete suggestions for a partial query stophy_get_credits Check your remaining credit balance

Each tool call costs one credit. stophy_get_credits is free.

What changed on the hosted server

The hosted Stophy API now includes a Streamable HTTP MCP route at /v1/mcp.

• Tool execution uses the same credit metering, refunds, request logging, and normalized response shapes as the REST API.

• The REST API and MCP tools now share the same validation schemas, so accepted parameters stay aligned across both surfaces.

• Path-based MCP auth is supported for clients that cannot send Authorization headers.

• Concurrency limiting keys hosted MCP path-auth requests by API key instead of grouping them under a shared IP bucket.

Environment variables

Variable Required Description STOPHY_API_KEY Yes Your Stophy API key from stophy.dev/dashboard

Python SDK

The stophy package for Python: a client for search, video details, transcripts, comments, channels, and playlists.

CLI

Use Stophy from the terminal for YouTube search, transcripts, comments, channels, and playlists.

Setup

Claude Desktop

Add this to your Claude Desktop config file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json

{
 "mcpServers": {
 "stophy": {
 "command": "npx",
 "args": ["-y", "@stophy/mcp"],
 "env": {
 "STOPHY_API_KEY": "st_YOUR_API_KEY"
 }
 }
 }
}

If you see a spawn npx ENOENT error, Node.js is not installed or not in your PATH. Install it from nodejs.org (LTS version), then fully restart Claude Desktop.

Claude Code

Recommended: hosted endpoint with header auth, if your Claude Code version supports Streamable HTTP MCP servers.

claude mcp add --transport http stophy https://api.stophy.dev/v1/mcp \
 --header "Authorization: Bearer $STOPHY_API_KEY"

Or run the local npm server, which reads STOPHY_API_KEY from the environment:

claude mcp add stophy -e STOPHY_API_KEY=st_YOUR_API_KEY -- npx -y @stophy/mcp

Only if your client cannot pass headers, fall back to the path-auth endpoint. The key is exposed in the URL (see the warning above):

claude mcp add --transport http stophy https://api.stophy.dev/v1/mcp/st_YOUR_API_KEY

Cursor

Open Cursor Settings

Go to Features > MCP Servers

Click "+ Add new global MCP server" and paste:

Refresh the MCP server list. The Stophy tools will appear automatically in the Composer Agent.

VS Code

Add to your User Settings JSON (Ctrl+Shift+P → Preferences: Open User Settings (JSON)):

{
 "mcp": {
 "inputs": [
 {
 "type": "promptString",
 "id": "apiKey",
 "description": "Stophy API Key",
 "password": true
 }
 ],
 "servers": {
 "stophy": {
 "command": "npx",
 "args": ["-y", "@stophy/mcp"],
 "env": {
 "STOPHY_API_KEY": "${input:apiKey}"
 }
 }
 }
 }
}

Or add it to .vscode/mcp.json in your project to share the config with your team:

{
 "inputs": [
 {
 "type": "promptString",
 "id": "apiKey",
 "description": "Stophy API Key",
 "password": true
 }
 ],
 "servers": {
 "stophy": {
 "command": "npx",
 "args": ["-y", "@stophy/mcp"],
 "env": {
 "STOPHY_API_KEY": "${input:apiKey}"
 }
 }
 }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json: