Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@stophy/mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@stophy/mcp

YouTube for AI Agents. Search, transcripts, comments, channels, playlists. All as MCP tool calls.

Quick start

env STOPHY_API_KEY=st_YOUR_API_KEY npx -y @stophy/mcp

Setup

Get an API key at stophy.dev/dashboard.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows:

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

Claude Code

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

Cursor

.cursor/mcp.json in your project, or ~/.cursor/mcp.json globally:

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

Windsurf

~/.codeium/windsurf/mcp_config.json:

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

Tools

stophy_search_videos

Search YouTube by keyword. If you already have a video URL, use stophy_get_video instead.

Arguments:

q (required): search query
type: "video" | "short" | "channel" | "playlist"
uploadDate: "hour" | "today" | "week" | "month" | "year"
duration: "short" (under 4 min) | "medium" (4-20 min) | "long" (over 20 min)
sortBy: "relevance" | "popularity" | "date" | "rating"
continuationToken: from the previous response to get the next page

Example:

{
  "name": "stophy_search_videos",
  "arguments": {
    "q": "typescript tutorial",
    "uploadDate": "week",
    "type": "video"
  }
}

Returns:

{
  "items": [
    {
      "type": "video",
      "id": "zxRUQ9foH5w",
      "videoUrl": "https://youtube.com/watch?v=zxRUQ9foH5w",
      "title": "Running JavaScript in TypeScript React",
      "author": "Nexion Analytics",
      "viewCount": 6,
      "duration": "4:41",
      "publishedAt": "2026-05-30T13:52:55.499Z"
    }
  ],
  "continuationToken": "4qmFsgJ..."
}

stophy_get_video

Get details, transcript, or comments for a video. If you're looking for videos on a topic, use stophy_search_videos instead.

Arguments:

videoUrl (required): YouTube video URL
type (required): "details" | "transcript" | "comments"
sortBy: "top" | "latest" — for comments only
continuationToken: next page of comments, or a comment's repliesToken to fetch its replies

Example:

{
  "name": "stophy_get_video",
  "arguments": {
    "videoUrl": "https://youtube.com/watch?v=d56mG7DezGs",
    "type": "transcript"
  }
}

Returns (transcript):

{
  "videoId": "d56mG7DezGs",
  "language": { "code": "en", "name": "en", "isAutoGenerated": true },
  "segments": [
    { "text": "welcome to the ultimate typescript", "start": 2.08, "duration": 3.6 }
  ]
}

Returns (comments):

{
  "videoId": "d56mG7DezGs",
  "sortBy": "top",
  "items": [
    {
      "id": "UgwfjLGxYnE9fEmwwxR4AaABAg",
      "text": "This was honestly just the right amount of information...",
      "author": "@Ramkatral",
      "likeCount": 145,
      "replyCount": 5,
      "repliesToken": "Eg0SC2Q1Nm1HN0RlekdzGA..."
    }
  ],
  "continuationToken": "4qmFsgJ..."
}

To read replies, call again with type: "comments" and continuationToken set to the comment's repliesToken.

stophy_get_channel

Browse a channel's content. If you have a specific video URL, use stophy_get_video instead.

Arguments:

channelUrl (required): youtube.com/@handle or youtube.com/channel/UCxxx
tab: "video" (default) | "short" | "playlist" | "about"
sortBy: "latest" | "popular" | "oldest" — video tab only
continuationToken: from the previous response to get the next page

Example:

{
  "name": "stophy_get_channel",
  "arguments": {
    "channelUrl": "https://youtube.com/@t3dotgg",
    "tab": "video",
    "sortBy": "latest"
  }
}

Returns:

{
  "channel": {
    "name": "Theo - t3.gg",
    "handle": "@t3dotgg",
    "subscriberCount": "539K subscribers",
    "isVerified": true
  },
  "tab": "video",
  "items": [
    {
      "videoUrl": "https://youtube.com/watch?v=_goOUJkkxUk",
      "title": "Anthropic fights back",
      "viewCount": 119000,
      "duration": "28:03"
    }
  ],
  "continuationToken": "4qmFsgLdCBIYVUNiUlAzYzc1N2xXZz..."
}

The about tab returns the full profile — country, joinedDate, viewCount, links[] — but no items or continuationToken.

stophy_get_playlist

Get all videos in a playlist.

Arguments:

playlistUrl (required): youtube.com/playlist?list=PLxxx
continuationToken: from the previous response to get the next page

Example:

{
  "name": "stophy_get_playlist",
  "arguments": {
    "playlistUrl": "https://youtube.com/playlist?list=PLTjRvDozrdlxEIuOBZkMAK5uiqp8rHUax"
  }
}

Returns:

{
  "playlist": {
    "title": "JavaScript Tutorials",
    "author": "Programming with Mosh",
    "videoCount": "25"
  },
  "items": [
    {
      "videoUrl": "https://youtube.com/watch?v=upDLs1sn7g4",
      "title": "What is JavaScript?",
      "duration": "5:12",
      "viewCount": 987000
    }
  ],
  "continuationToken": "4qmFsgJ..."
}

stophy_get_suggestions

YouTube autocomplete for a partial query.

Arguments:

q (required): partial query
hl: language code, e.g. en, fr. Defaults to en
gl: country code, e.g. US, GB. Defaults to US

Example:

{
  "name": "stophy_get_suggestions",
  "arguments": { "q": "react hooks", "hl": "en", "gl": "US" }
}

Returns:

{
  "suggestions": [
    "react hooks",
    "react hooks explained",
    "react hooks tutorial"
  ]
}

stophy_get_credits

Check your credit balance. Doesn't cost a credit.

{
  "name": "stophy_get_credits",
  "arguments": {}
}

Returns:

{
  "credits": 39152
}

Pagination

Any tool that returns continuationToken can be paged. Pass it back in the next call with the same arguments. When it's null, you're at the end.

When there's no data

If a video has no transcript, comments are turned off, or there are no replies, you get a 200 with empty instead of items:

{
  "empty": {
    "code": "EMPTY_TRANSCRIPT_SEGMENTS",
    "message": "No transcript segments found."
  }
}

Possible codes: EMPTY_TRANSCRIPT_SEGMENTS, EMPTY_COMMENTS, EMPTY_COMMENT_REPLIES.

Errors

Errors come back as plain text in the tool response:

Stophy error (UNAUTHORIZED): Invalid API key.

Stophy error (MISSING_API_KEY): STOPHY_API_KEY environment variable is not set. Get a key at https://stophy.dev/dashboard.

Environment variables

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

License

MIT