Creator Research MCP

A TypeScript MCP server that fetches content data — YouTube, TikTok, Instagram, Twitter/X, LinkedIn, articles, PDFs — so that the LLM client (ChatGPT, Claude) can analyze what content performs well, what patterns repeat, and how to turn that into courses, scripts, or strategy.

Works with any MCP client: Claude Desktop / Claude Code (stdio), ChatGPT and remote clients (Streamable HTTP).

What it's for

Point your LLM client at a channel, a video, or a competitor's profile and ask things like:

• "What are @channel's best-performing videos, and why do they outperform the rest?" — list_videos ranks by a median+MAD outlier score, not just raw views, so a single viral fluke doesn't skew the read.

• "Get the transcripts of their top 3 videos and write me a script in the same style." — get_transcript pulls captions/subtitles + engagement so the LLM can read and imitate the actual content, not just metadata.

• "What part of this video made people rewatch it — and what killed their interest?" — get_retention_moments matches the replay heatmap to the transcript by timestamp, so you get the actual words said at each hotspot/coldspot instead of a bare timestamp.

• "How is this video growing — is it still gaining views a week later?" — get_metrics_history turns repeated measurements into real velocity (views/day, engagement/view), and is explicit about what it can't compute yet, instead of guessing.

• "Compare these 5 creators: who posts more often, who covers what topics, what's missing?" — analyze_creator/compare_creators give deterministic stats (cadence, keywords, format performance) across multiple channels at once.

• "What do people keep asking for in the comments that I haven't made yet?" — get_content_ideas clusters repeated requests/questions by shared vocabulary and ranks them by how many people asked plus engagement — a single comment isn't a pattern, so singletons are dropped.

• "Turn what these videos teach into a course outline / learning roadmap." — generate_course/generate_roadmap deduplicate topics across saved analyses and order them by level.

Every number the server returns is either fetched directly from the platform or computed with a documented formula (median absolute deviation for outliers, real deltas for growth) — never fabricated. Where a platform genuinely doesn't expose something (Instagram profile listings, Twitter/X threads, LinkedIn behind login), the capabilities tool says so explicitly instead of returning a plausible-looking guess.

Related MCP server: Recast MCP

Design: client-reasoning only

The server fetches data, it never analyzes — there's no AI engine running inside it.

list_videos(channel)        →  stats + outlierScore + tags (yt-dlp or YouTube Data API)
get_transcript(url)         →  metadata + subtitles/captions (yt-dlp/FxTwitter/scraping)
get_comments(url)           →  public YouTube/Instagram comments
       ↓
The client LLM (ChatGPT/Claude) analyzes the text inside the conversation
       ↓
save_analysis(url, facets)  →  persisted, queryable and comparable later

This is intentional: the server needs no RAM/CPU/GPU for AI — it only fetches and structures data, so it's cheap and fast to run anywhere. See docs/architecture.md for the full design.

Installation

Requirements: Node ≥ 20, yt-dlp on your PATH (brew install yt-dlp / apt install yt-dlp). Everyone runs their own copy, with their own credentials — there is no shared server and no data is centralized anywhere.

Option 1 — npx (recommended, no cloning)

{
  "mcpServers": {
    "creator-research": {
      "command": "npx",
      "args": ["-y", "creator-research-mcp"]
    }
  }
}

Paste this into your Claude Desktop/Code config. The SQLite database is created automatically at ~/.creator-research/. Every credential is optional (see .env.example) — if you want to use YOUTUBE_API_KEY, export it before opening the MCP client, or run HTTP mode (below), which loads a .env file automatically.

npx creator-research-mcp http   # HTTP mode on :3333, for ChatGPT via a tunnel

Option 2 — clone the repo (for development or contributing)

git clone https://github.com/CleanCod3Systems/creator-research-mcp.git
cd creator-research-mcp
pnpm install
cp .env.example .env   # fill in your credentials (all optional)
pnpm build
pnpm mcp:stdio        # stdio (Claude Desktop/Code, Cursor)
pnpm mcp:http         # HTTP :3333 (ChatGPT via Cloudflare Tunnel)

The binary loads .env automatically on startup (via dotenv) — nothing needs to be exported by hand. .env is never committed (gitignored); .env.example documents every variable.

Connecting to Claude Desktop

claude_desktop_config.json (if you cloned the repo instead of using npx):

{
  "mcpServers": {
    "creator-research": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/repo", "mcp:stdio"]
    }
  }
}

Try the capabilities tool — it should list the providers and their limitations.

Connecting to ChatGPT

ChatGPT's MCP connectors require a Plus/Pro plan and a remote HTTPS server:

# 1. HTTP server with a security token
MCP_AUTH_TOKEN=$(openssl rand -hex 16) pnpm mcp:http     # note the token

# 2. Free HTTPS tunnel
brew install cloudflared
cloudflared tunnel --url http://localhost:3333
# → gives you https://some-random-name.trycloudflare.com

In ChatGPT: Settings → Apps & Connectors → Advanced settings → Developer mode → Create connector → URL: https://some-random-name.trycloudflare.com/mcp?key=YOUR_TOKEN.

Notes: without MCP_AUTH_TOKEN, anyone with the URL can use your server. The trycloudflare URL changes on every run and Cloudflare can kill it without notice; for a stable URL, use a named tunnel (free with a Cloudflare account) or Tailscale Funnel.

YOUTUBE_API_KEY (optional, free, recommended)

Without it, list_videos still works via yt-dlp (views are fine, likes aren't exact, and occasionally come back null). With a free key from the YouTube Data API v3:

• list_videos returns exact likes, real SEO tags, and no nulls (1 quota unit per batch of 50 videos — the free 10,000/day quota is more than enough)

• get_trending_videos becomes available (what's currently trending on YouTube by region/category)

export YOUTUBE_API_KEY="your-key-here"

Available tools

Typical flow: "get me the most-viewed videos from @channel, the transcript of the top 3, and turn that into a reel script" → list_videos → get_transcript × 3 → the LLM analyzes and writes the script → optionally save_analysis to query it later.

Useful env vars: YTDLP_EXTRA_ARGS (for special local environments), YOUTUBE_API_KEY, MCP_AUTH_TOKEN, DATABASE_PATH.

Providers and honest limitations

• Instagram: public individual post/reel URLs are supported on a best-effort basis. Metadata includes author details, available engagement, thumbnails, captions, and carousel items. Public comments are best-effort and may be unavailable. Stories/highlights may expire, and image-only posts may have no text beyond their caption. There is no automatic profile listing. Pass individual URLs to get_transcript (it accepts urls in batch), or manually record followers/likes/comments with import_profile_snapshot to track profile growth over time. Credentials and browser cookies are not requested, and login is never bypassed.

• Twitter/X: only individual public tweets (via FxTwitter); profiles and replies are out of scope.

• TikTok: yt-dlp best-effort; no comments support.

• The capabilities tool exposes all of this at runtime so the client LLM never promises something the server can't actually do.

Publishing a new version (maintainers)

The .github/workflows/release.yml workflow does everything: pushing a v* tag builds, tests, and publishes all 4 workspace packages to npm (pnpm automatically replaces workspace:* with the real versions).

# 1. bump the version in all 4 package.json files (core/db/providers/mcp-server) to the same number
# 2. commit + push to main
git tag v0.1.0 && git push --tags

Requires the NPM_TOKEN secret (repo Settings → Secrets → Actions on GitHub) with an npm automation token. The ci.yml workflow runs build/typecheck/lint/test on every push/PR to main, no secret required.

Architecture

• packages/core — pure domain logic (Zod) + ports (interfaces). No I/O.

• packages/db — Drizzle + SQLite (WAL).

• packages/providers — one adapter per platform (YouTube, TikTok, Instagram, Twitter, LinkedIn, web, PDF).

• apps/mcp-server — the active MCP tools. Dual transport (stdio/HTTP).

Full detail in docs/architecture.md.

Security

• .env is never committed (it's in .gitignore). It holds your real MCP_AUTH_TOKEN and YOUTUBE_API_KEY — copy .env.example and fill in your own credentials, never share your .env or paste it into an issue/PR.

• Generate MCP_AUTH_TOKEN with openssl rand -hex 32 (or longer). The comparison in http.ts runs in constant time (crypto.timingSafeEqual) so the token can't leak through timing. If you run the server without this token, anyone with the tunnel URL can use it — the server itself warns about this on stderr at startup.

• filePath in get_transcript reads files from the disk the server runs on (.md/.txt, plus media files for basic metadata), with no sandboxing by design (it's the fallback path for local content). If you expose the server over HTTP with a public tunnel, any connected MCP client can request any file with those extensions that the process can read. Don't run this on a machine with sensitive .md/.txt files accessible to the process's user, or restrict access at the network/tunnel level.

• No shell: true calls anywhere: every yt-dlp invocation uses execFile with arguments as an array (never string interpolation), which rules out command injection even if a URL contains shell metacharacters.

• data/*.db (SQLite) stays 100% local and gitignored — this is where your real search/ analysis history accumulates. Don't upload it anywhere if it contains data you'd rather keep private.

• Before making a repo public: run git log -p -- .env (in case a commit ever included .env) and, if anything shows up, follow GitHub's guide to purge secrets from history — deleting the file in a new commit is not enough, it stays in history.

Contributing

pnpm install
pnpm build       # compile all workspace packages
pnpm typecheck    # includes test files, unlike build
pnpm lint         # eslint
pnpm test         # vitest, per package

Pull requests should keep all four commands passing. There's no separate style guide beyond what ESLint/Prettier already enforce (pnpm format to auto-fix).

License

MIT