@mambalabsdev/mcp-youtube-channel-transcript-extractor 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mamba Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# YouTube Channel Stats Extractor MCP Server
+
+[![Smithery](https://smithery.ai/badge/mambabuilt/mcp-youtube-channel-transcript-extractor)](https://smithery.ai/servers/mambabuilt/mcp-youtube-channel-transcript-extractor) [![Glama score](https://glama.ai/mcp/servers/mambalabsdev/mcp-youtube-channel-transcript-extractor/badges/score.svg)](https://glama.ai/mcp/servers/mambalabsdev/mcp-youtube-channel-transcript-extractor) [![npm version](https://img.shields.io/npm/v/@mambalabsdev/mcp-youtube-channel-transcript-extractor)](https://www.npmjs.com/package/@mambalabsdev/mcp-youtube-channel-transcript-extractor) [![npm downloads](https://img.shields.io/npm/dm/@mambalabsdev/mcp-youtube-channel-transcript-extractor)](https://www.npmjs.com/package/@mambalabsdev/mcp-youtube-channel-transcript-extractor) [![license](https://img.shields.io/github/license/mambalabsdev/mcp-youtube-channel-transcript-extractor)](https://github.com/mambalabsdev/mcp-youtube-channel-transcript-extractor/blob/main/LICENSE)
+
+MCP server for the Mamba Labs **YouTube Channel Stats Extractor** actor on Apify.
+
+Resolve a company domain or YouTube handle to the channel with subscriber count and channel metadata.
+
+## What it does
+
+Resolve a company domain, or a YouTube handle, to that company's YouTube channel. Returns the subscriber count, the stable UC channel id, channel name, creation date and description, as one flat Clay ready row. Subscriber counts are rounded by YouTube above roughly a thousand subscribers, on the page and in its official API alike, and the row flags that. Optional transcript pulling is available and is CURRENTLY GATED by YouTube: the caption track list is readable and the caption content endpoint returns an empty body without a proof of origin token, which the row reports as not_extractable rather than as a video having no captions. No API key needed. Read only; requires an APIFY_TOKEN and consumes Apify credits per call.
+
+## Quick start
+
+Add this to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "mamba-youtube-channel-stats": {
+      "command": "npx",
+      "args": ["-y", "@mambalabsdev/mcp-youtube-channel-transcript-extractor"],
+      "env": { "APIFY_TOKEN": "your-apify-token" }
+    }
+  }
+}
+```
+
+## Prerequisites
+
+- Node.js 18 or newer
+- An Apify API token from [console.apify.com/account/integrations](https://console.apify.com/account/integrations)
+
+The actor is pay per event and consumes Apify credits per call. Pricing is on the
+[actor page](https://apify.com/mambalabs/youtube-channel-transcript-extractor).
+
+## Example prompts
+
+- "How many YouTube subscribers does stripe.com have?"
+- "Find the YouTube channel id for hubspot.com."
+- "Does gitlab.com run a YouTube channel, and when was it created?"
+
+## Tool and inputs
+
+Tool: `get_youtube_channel_stats`
+
+| Input | Type | Meaning |
+|---|---|---|
+| `company_domain` | string | Bare company domain, for example shopify.com. Supply this or a handle. With a domain the actor runs full discovery; with a handle it skips straight to |
+| `company_name` | string | Optional. Improves search accuracy and is what the identity gate checks a discovered profile against, so supplying it reduces wrong matches. |
+| `handle` | string | Optional. A YouTube handle such as @shopify, or a full channel URL. Supplying it skips discovery and goes straight to the channel. |
+| `includeFollowerCounts` | boolean | When "true" (default) the profile page is fetched and the counts are extracted. Set "false" to resolve the profile URL only, which is cheaper and need |
+| `skipCache` | boolean | When "false" (default) a successful lookup is cached for seven days and reused. Set "true" to force a fresh fetch. Sent as a string for Clay compatibi |
+| `includeTranscripts` | boolean | When "true", full timestamped transcripts are pulled for the most recent videos on the channel and returned as one row per video. Default is "false" b |
+| `transcriptVideoCount` | string | How many of the channel's most recent videos to pull transcripts for, when transcripts are on. Default 5. Each video is one extra fetch and one extra  |
+
+## Reading the output
+
+Every row carries a per platform `_status` field, and it is the field to read
+first. The vocabulary is the same across the whole Mamba Labs social family:
+
+| Status | Meaning |
+|---|---|
+| `ok` | fetched and parsed, the value is there |
+| `not_found` | we looked and there is no such profile |
+| `not_extractable` | the profile exists and the value is not on the wire to us |
+| `blocked` | the platform refused us, worth retrying later |
+| `identity_mismatch` | we found a real profile and it belongs to someone else |
+| `skipped` | you did not ask for this platform |
+
+**`false` and `null` are never interchangeable.** `false` means we looked and the
+answer is no. `null` means we could not look. If you filter for companies with no
+presence, filter on `false`, because `null` rows are unknown rather than absent.
+
+## Full actor documentation
+
+[apify.com/mambalabs/youtube-channel-transcript-extractor](https://apify.com/mambalabs/youtube-channel-transcript-extractor)
+
+## Mamba Labs GTM Suite
+
+Mamba Labs builds a fleet of GTM enrichment actors that share one flat, Clay
+ready output convention, so their rows join on `company_domain` with no cleaning
+step. Full fleet: [apify.com/mambalabs](https://apify.com/mambalabs)
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+The latest published `1.x` release of
+`@mambalabsdev/mcp-company-social-presence-mapper` receives security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x     | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a vulnerability
+
+Please do not open a public GitHub issue for security reports.
+
+Email security reports to **labs@mambamindsetgrowth.com** with:
+
+- a description of the issue and its impact,
+- steps to reproduce, and
+- any relevant logs or proof of concept.
+
+We aim to acknowledge reports within 3 business days and to provide a remediation
+timeline after triage. Coordinated disclosure is appreciated.
+
+## Handling of credentials
+
+This server reads an `APIFY_TOKEN` from the environment and uses it only to call
+the Apify API on your behalf. The token is never logged or written to disk by this
+package. Treat your `APIFY_TOKEN` as a secret and rotate it at
+https://console.apify.com/account/integrations if you believe it has been exposed.

package/build/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+// Distinctive UA so Apify run meta.userAgent marks MCP-originated runs.
+const USER_AGENT = `mambalabs-mcp ${pkg.name}@${pkg.version}`;
+const APIFY_TOKEN = process.env.APIFY_TOKEN;
+// Drop undefined values so optional inputs are not sent to the actor at all.
+function compact(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+// The actor types its switches as strings ("true"/"false") for Clay
+// compatibility, because Clay sends every input as a string and a boolean typed
+// field silently receives "false" and reads it as truthy. The model gets a real
+// boolean and the actor gets the string it validates.
+function boolToString(v) {
+    return v === undefined ? undefined : v ? "true" : "false";
+}
+// actorPath is the actor's IMMUTABLE Apify actor id, not its slug, so a Store
+// rename never breaks these calls.
+async function runActor(actorPath, actorLabel, input) {
+    if (!APIFY_TOKEN) {
+        return { isError: true, content: [{ type: "text", text: "APIFY_TOKEN is not set. Create a token at https://console.apify.com/account/integrations and set it as the APIFY_TOKEN environment variable." }] };
+    }
+    // memory=1024 is deliberate and matches the actor's declared
+    // defaultRunOptions.memoryMbytes. run-sync-get-dataset-items runs at 2048 MB
+    // unless told otherwise, and `apify-actor-start` bills once per GB with a
+    // minimum of one, so leaving the default in place would charge the caller
+    // more start events per run than the actor asks for. Keep this in step with
+    // the actor's defaultRunOptions.
+    const url = `https://api.apify.com/v2/acts/${actorPath}/run-sync-get-dataset-items?timeout=300&memory=1024`;
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${APIFY_TOKEN}`,
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+            },
+            body: JSON.stringify(input),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Could not reach the Apify API: ${message}` }] };
+    }
+    if (!response.ok) {
+        let detail = "";
+        try {
+            const body = (await response.json());
+            if (body?.error?.message)
+                detail = ` ${body.error.message}`;
+        }
+        catch {
+            detail = "";
+        }
+        let message;
+        switch (response.status) {
+            case 401:
+                message = "Invalid Apify token. Check your APIFY_TOKEN environment variable.";
+                break;
+            case 402:
+                message = "Insufficient Apify credits. Check your account balance at https://console.apify.com/billing";
+                break;
+            case 408:
+                message = `The ${actorLabel} run timed out after 300 seconds. Try again, or run the actor on Apify directly for longer jobs.`;
+                break;
+            default:
+                message = `Apify request to ${actorLabel} failed with status ${response.status}.${detail}`;
+        }
+        return { isError: true, content: [{ type: "text", text: message }] };
+    }
+    // A 2xx normally carries the dataset array. Pass actor output through
+    // unchanged: the wrapper must never reinterpret a status field, because
+    // not_extractable, blocked and not_found are different answers and collapsing
+    // them is exactly the defect the actor was built to avoid.
+    const items = await response.json();
+    return { content: [{ type: "text", text: JSON.stringify(items, null, 2) }] };
+}
+const server = new McpServer({
+    name: "mamba-youtube-channel-stats",
+    version: pkg.version,
+});
+// YouTube Channel Stats Extractor (immutable actor ID 6hSpD3kd2s2IQ4VSs)
+server.registerTool("get_youtube_channel_stats", {
+    title: "Get YouTube Channel Stats",
+    description: "Resolve a company domain, or a YouTube handle, to that company's YouTube channel. Returns the subscriber count, the stable UC channel id, channel name, creation date and description, as one flat Clay ready row. Subscriber counts are rounded by YouTube above roughly a thousand subscribers, on the page and in its official API alike, and the row flags that. Optional transcript pulling is available and is CURRENTLY GATED by YouTube: the caption track list is readable and the caption content endpoint returns an empty body without a proof of origin token, which the row reports as not_extractable rather than as a video having no captions. No API key needed. Read only; requires an APIFY_TOKEN and consumes Apify credits per call.",
+    annotations: {
+        title: "Get YouTube Channel Stats",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    inputSchema: {
+        company_domain: z.string()
+            .optional()
+            .describe("Bare company domain, for example shopify.com. Supply this or a handle. With a domain the actor runs full discovery; with a handle it skips straight to the fetch."),
+        company_name: z.string()
+            .optional()
+            .describe("Optional. Improves search accuracy and is what the identity gate checks a discovered profile against, so supplying it reduces wrong matches."),
+        handle: z.string()
+            .optional()
+            .describe("Optional. A YouTube handle such as @shopify, or a full channel URL. Supplying it skips discovery and goes straight to the channel."),
+        includeFollowerCounts: z.boolean()
+            .optional()
+            .describe("When \"true\" (default) the profile page is fetched and the counts are extracted. Set \"false\" to resolve the profile URL only, which is cheaper and needs no proxy. Sent as a string for Clay compatibility."),
+        skipCache: z.boolean()
+            .optional()
+            .describe("When \"false\" (default) a successful lookup is cached for seven days and reused. Set \"true\" to force a fresh fetch. Sent as a string for Clay compatibility."),
+        includeTranscripts: z.boolean()
+            .optional()
+            .describe("When \"true\", full timestamped transcripts are pulled for the most recent videos on the channel and returned as one row per video. Default is \"false\" because transcripts are the expensive half of this actor and most buyers want channel stats only. Sent as a string for Clay compatibility."),
+        transcriptVideoCount: z.string()
+            .optional()
+            .describe("How many of the channel's most recent videos to pull transcripts for, when transcripts are on. Default 5. Each video is one extra fetch and one extra billable transcript event, so this is the dial that sets the cost of a transcript run."),
+    },
+}, async ({ company_domain, company_name, handle, includeFollowerCounts, skipCache, includeTranscripts, transcriptVideoCount }) => {
+    return runActor("6hSpD3kd2s2IQ4VSs", "YouTube Channel Stats Extractor", compact({
+        company_domain,
+        company_name,
+        handle,
+        includeFollowerCounts: boolToString(includeFollowerCounts),
+        skipCache: boolToString(skipCache),
+        includeTranscripts: boolToString(includeTranscripts),
+        transcriptVideoCount,
+    }));
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mambalabsdev/mcp-youtube-channel-transcript-extractor",
+  "version": "1.0.0",
+  "description": "MCP server for the Mamba Labs YouTube Channel Stats Extractor actor on Apify. Resolve a company domain or YouTube handle to the channel with subscriber count and channel metadata.",
+  "type": "module",
+  "bin": {
+    "mcp-youtube-channel-transcript-extractor": "./build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x build/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "youtube",
+    "channel-stats",
+    "subscribers",
+    "transcripts",
+    "apify",
+    "clay"
+  ],
+  "author": "Mamba Labs <labs@mambamindsetgrowth.com>",
+  "license": "MIT",
+  "homepage": "https://apify.com/mambalabs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mambalabsdev/mcp-youtube-channel-transcript-extractor"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.0"
+  },
+  "mcpName": "com.mambabuilt/mcp-youtube-channel-transcript-extractor"
+}