# youtube-script-mcp

A remote MCP server exposing 4 tools for YouTube script/title strategy, connectable from Claude, ChatGPT, or any MCP client.

## Tools

1. **analyze_competitor_titles** — `channelUrl`, optional `keyword`. Pulls recent videos, finds outlier (above-average) titles, returns winning patterns, oversaturated patterns, and fresh title recommendations.
2. **generate_channel_dna** — `bio`, optional `competitorUrls` (up to 3). Returns 1-4 pillars, 1-4 title formulas, a positioning gap, and a channel DNA summary.
3. **generate_hooks** — `niche`, optional `competitorUrls` (up to 3), optional `count` (1-4). Returns original hook types inspired by competitor patterns (never copies wording).
4. **generate_script** — `scriptStructure`, `pillar`, `formula`, `hookType`, `titleIdea`. Returns a full script draft.

## Setup

```bash
npm install
cp .env.example .env
# fill in .env with your keys
npm run build
npm start
```

For local dev without building: `npm run dev`

## Required API keys

- **YOUTUBE_API_KEY** — YouTube Data API v3 key from [Google Cloud Console](https://console.cloud.google.com/). Enable "YouTube Data API v3" on the project, then create an API key.
- **OPENAI_API_KEY** — from [platform.openai.com](https://platform.openai.com/api-keys).
- **SERPER_API_KEY** — from [serper.dev](https://serper.dev). Optional but recommended: without it, saturation checks in `analyze_competitor_titles` are skipped.

## Deploying on Replit

1. Add the three keys above as Replit Secrets (not hardcoded).
2. Set the run command to `npm run build && npm start`.
3. Once running, your MCP endpoint is `https://<your-repl-domain>/mcp`.

## Connecting from Claude / ChatGPT

Both accept a remote MCP server URL. Give them:

```
https://<your-deployed-domain>/mcp
```

as the connector URL. The server uses the Streamable HTTP transport (stateful sessions via the `Mcp-Session-Id` header), which both Claude and ChatGPT's remote-connector support expects.

## Notes

- `resolveChannelId` in `src/youtube.ts` accepts `@handle` URLs, `/channel/UC...` URLs, legacy `/c/` and `/user/` URLs, or a raw channel ID.
- All AI-generated fields (patterns, pillars, hooks, scripts) come from OpenAI's `gpt-4o-mini` — swap the model string in `src/openai-client.ts` if you want a different one.
- This has not been run against live API keys in this environment (no network access here) — test locally with real keys before relying on it in production.