FrameFetch MCP Server

FrameFetch

Any social-video URL → metadata, transcript, insights & frames.
Agent-first video data API + MCP server. Pay per call, or with x402 (USDC) — no account.

---

FrameFetch turns one YouTube, YouTube Shorts, TikTok, Instagram Reels, Pinterest, or Reddit video URL into a single JSON response: metadata, engagement insights, a transcript (captions or Whisper), and parametrically-sampled frames (every Nth / 1-per-second / a time range, at any width). Built API-first and MCP-first for AI agents.

This repo is the open-source client + docs. The service itself runs at framefetch.net — you bring a free API key (or pay per call with x402); the backend stays hosted.

Why

An LLM can't watch a video. To reason about one it needs the video turned into text and images first — a transcript, metadata, and a few frames. FrameFetch returns all three from a URL, across six platforms, through one schema.

Install

npm install framefetch

Node 18+ (uses built-in fetch). Get a free key: framefetch.net.

Quick start

import { FrameFetch } from 'framefetch';

const ff = new FrameFetch({ apiKey: process.env.FRAMEFETCH_API_KEY });

const r = await ff.extract({
  url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
  fields: ['metadata', 'transcript', 'frames'],
  frames: { mode: 'fps', fps: 1, width: 480 },
});

console.log(r.metadata.title);   // "Me at the zoo"
console.log(r.transcript.text);  // "Alright, so here we are…"
console.log(r.frames.count);     // 19

Scoped helpers

await ff.metadata(url);    // title, author, duration, views, likes…
await ff.transcript(url);  // captions, else Whisper
await ff.frames(url, { mode: 'fps', fps: 1, width: 512 });
await ff.platforms();      // capability matrix (no key)
await ff.status();         // live service health (no key)

No signup

const ff = new FrameFetch();                              // no key
await ff.demo('https://youtu.be/jNQXAC9IVRw');            // instant metadata, rate-limited
const { key } = await ff.createKey('[email protected]');    // self-serve key + free credit

Use it from an MCP agent

FrameFetch ships an MCP server (Streamable HTTP) with the tools framefetch_extract and framefetch_platform_capabilities. Add it to Claude, Cursor, or any MCP client:

{
  "mcpServers": {
    "framefetch": {
      "url": "https://framefetch.net/mcp",
      "headers": { "Authorization": "<YOUR_FRAMEFETCH_KEY>" }
    }
  }
}

Or one line:

claude mcp add --transport http framefetch https://framefetch.net/mcp \
  --header "Authorization: <YOUR_FRAMEFETCH_KEY>"

Pay without an account (x402)

Autonomous agents can pay per call in USDC via x402 on Base — no signup, no human in the loop. Discoverable in the x402 Bazaar and at /.well-known/x402.json. Humans can use a free tier, prepaid credits, or a Stripe card.

Errors

import { FrameFetchError } from 'framefetch';
try {
  await ff.transcript(url);
} catch (e) {
  if (e instanceof FrameFetchError && e.status === 402) {
    // out of credit — top up at framefetch.net or via x402
  }
}

API surface

Method	Endpoint	Auth
extract({ url, fields, frames })	POST /v1/extract	key
metadata(url)	POST /v1/metadata	key
transcript(url)	POST /v1/transcript	key
frames(url, spec)	POST /v1/frames	key
platforms()	GET /v1/platforms	—
status()	GET /v1/status	—
demo(url)	POST /v1/demo	—
createKey(email)	POST /v1/keys	—

Full OpenAPI: framefetch.net/openapi.json · Docs: framefetch.net/docs

Links

Website · Docs · Pricing · Status · Guide: giving an agent video data

License

MIT