# scribefy-mcp

[MCP](https://modelcontextprotocol.io) server for [Scribefy](https://scribefy.app) — extract YouTube transcripts from Claude Desktop, Cursor, Windsurf, ChatGPT custom GPTs, or any other MCP-compatible client.

> **Live now** — set it up in a minute below, or try the web app at **[scribefy.app](https://scribefy.app)**.

## Why

Most YouTube transcript tools live in browser extensions or one-off web UIs. This wraps Scribefy's API into the MCP standard so your AI assistant can pull a transcript whenever a user pastes a YouTube link — no manual copy-paste, no separate tabs.

## Requirements

- Node 20+
- A Scribefy account on the **API + MCP** plan ($25/mo) for an API key. You can install without a key first — the MCP host registers the server cleanly and you'll get a friendly nudge when you try to use a tool — then add your key from [scribefy.app/dashboard](https://scribefy.app/dashboard) to start extracting.

## Setup

### Claude Desktop

Open the config file (`Settings → Developer → Edit Config`):

```json
{
  "mcpServers": {
    "scribefy": {
      "command": "npx",
      "args": ["-y", "scribefy-mcp"],
      "env": {
        "SCRIBEFY_API_KEY": "sk_live_…"
      }
    }
  }
}
```

Restart Claude Desktop. The `extract_transcript` tool appears in the available-tools panel.

### Cursor

`Settings → Cursor Settings → MCP → Add new MCP server`:

```json
{
  "scribefy": {
    "command": "npx",
    "args": ["-y", "scribefy-mcp"],
    "env": {
      "SCRIBEFY_API_KEY": "sk_live_…"
    }
  }
}
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "scribefy": {
      "command": "npx",
      "args": ["-y", "scribefy-mcp"],
      "env": {
        "SCRIBEFY_API_KEY": "sk_live_…"
      }
    }
  }
}
```

### Anywhere else

Any MCP host that supports stdio transport: spawn `npx -y scribefy-mcp` with `SCRIBEFY_API_KEY` in the env. The server speaks the standard [MCP](https://modelcontextprotocol.io) JSON-RPC over stdin/stdout.

## Tools exposed

Four tools. Three are free (research toolkit); only `extract_transcript` charges credits.

### `extract_transcript`

Pulls the transcript of a YouTube video.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | Full YouTube URL — `youtube.com/watch?v=…`, `youtu.be/…`, or `youtube.com/shorts/…` |
| `lang` | string | no | BCP-47 language code (e.g. `en`, `es`, `fr`, `zh-Hans`). Defaults to `en` |

**Returns:** Markdown with title, channel, duration, language, and the transcript split into segments with timestamps.

**Cost:** 1 credit (≤15 min) → 8 credits (2 h+). Cached transcripts are free.

### `search_videos`

Free-text YouTube search.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search query — same syntax YouTube's own search bar accepts |
| `limit` | number | no | Max results, 1–25 (default 10) |

**Returns:** Markdown list of title / channel / duration / views / URL for each result.

**Cost:** Free.

### `get_video_metadata`

Title, channel, duration, view count, upload date, and available caption tracks. **Does not** pull the transcript.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | Full YouTube URL |

**Returns:** Markdown summary plus a list of every caption track (authored ✏ or auto-generated ⚙) with its language code.

**Cost:** Free. Use this to inspect a video before deciding whether to extract, or to discover which caption languages are available.

### `get_related_videos`

YouTube's "Up next" feed for a video.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | Full YouTube URL of the seed video |
| `limit` | number | no | Max related videos, 1–25 (default 10) |

**Returns:** Same shape as `search_videos`.

**Cost:** Free.

### Tools coming in a future release

`list_channel_videos` and `get_video_comments` were planned for 0.3.0 but are deferred to 0.4.0 while we wait for upstream `youtubei.js` to publish fixes for YouTube's 2026 response-shape changes. Channel listing fails with HTTP 400 at the InnerTube layer, and `info.getComments()` is no longer attached to parsed `VideoInfo`. Both will return as soon as the library catches up.

## Skills

The repo ships an Agent Skill (a `SKILL.md` your assistant loads on demand) that teaches it how to use these tools *well* — vet candidates with the free tools before spending credits, prefer authored captions, lean on the free transcript cache, and cite answers with timestamps.

- [`skills/youtube-research`](skills/youtube-research/SKILL.md) — the YouTube research workflow: search → vet metadata → extract selectively → synthesize with `[mm:ss]` citations.

To use it in Claude Code, copy the folder into your project's `.claude/skills/` (or `~/.claude/skills/` to have it everywhere). Open Plugins-compatible hosts detect it straight from the repo.

## Configuration

| Env var | Required | Default | Notes |
|---|---|---|---|
| `SCRIBEFY_API_KEY` | yes | — | `sk_live_…` (production) or `sk_test_…` (Scribefy test mode) |
| `SCRIBEFY_API_BASE` | no | `https://api.scribefy.app` | Override for staging (`https://api-staging.scribefy.app`) or self-hosted instances |

## Troubleshooting

**`SCRIBEFY_API_KEY is required`**
Make sure the `env` block is set in your MCP host's config and the host actually loads it. Some hosts strip env vars by default — check their docs.

**`Scribefy rejected the API key`**
Either the key is wrong, the key was revoked, or your subscription is no longer on the API + MCP plan. Check [scribefy.app/dashboard](https://scribefy.app/dashboard).

**`Not enough credits`**
The tool returns the remaining balance and the cost in the error message. Top up at [scribefy.app/pricing](https://scribefy.app/pricing).

**The tool doesn't show up in my MCP client**
After editing the config, fully restart the client (not just the chat window). Tail the client's logs if available — most show MCP stderr there. The server prints `scribefy-mcp: ready` once it boots.

## License

MIT