Supadata MCP Server

Use Supadata in your AI agent: video transcripts, media metadata, web scraping, crawling, and site discovery. This repository is the Supadata MCP server (Model Context Protocol), which AI agents like Claude, ChatGPT and Cursor use to call Supadata.

Add to your AI agent

Click a button, then sign in with your Supadata account. No API key to copy.

• Claude: click Add to Claude, click Connect and sign in. Works in claude.ai, Claude Desktop and the mobile apps. On Team/Enterprise plans an Owner enables Supadata first in Admin settings → Connectors.
• ChatGPT: click Add to ChatGPT, click Connect and sign in.
• Cursor: click Add to Cursor, confirm Install, and Cursor opens the Supadata sign-in page.

Claude Code / Codex

# Claude Code: then run /mcp and choose Authenticate
claude mcp add --transport http supadata https://api.supadata.ai/mcp

# Codex
codex mcp add supadata --url https://api.supadata.ai/mcp
codex mcp login supadata

Other MCP clients can connect to the hosted server at https://api.supadata.ai/mcp (OAuth, or an x-api-key header), or run the local server below.

Features

• Video transcript extraction from YouTube, TikTok, Instagram, Twitter, and file URLs
• Web scraping, crawling, and URL discovery
• Media metadata retrieval from YouTube, TikTok, Instagram, and Twitter
• AI-powered structured data extraction from video content

Installation

For step-by-step setup in Claude, ChatGPT, Cursor, Claude Code, Codex, Windsurf, VS Code and other AI agents, see the AI agents guide.

Running

Stdio (default)

Running the package starts an MCP server on stdio. Use this when your AI agent should spawn the server locally with your API key instead of using the hosted server (for example a custom agent, or VS Code / Windsurf config files):

SUPADATA_API_KEY=your-api-key npx -y @supadata/mcp

Example client configuration:

{
  "mcpServers": {
    "supadata": {
      "command": "npx",
      "args": ["-y", "@supadata/mcp"],
      "env": { "SUPADATA_API_KEY": "your-api-key" }
    }
  }
}

Streamable HTTP (hosted)

The same tools are served over Streamable HTTP by the Cloudflare Worker in src/worker.ts, deployed at https://api.supadata.ai/mcp with OAuth 2.1. Run it locally with npm run dev (wrangler). Direct x-api-key header authentication is also accepted on /mcp.

An OAuth connection stays alive while it is used and expires after 30 days without use. Then clients have to log in again; Codex keeps retrying the expired login instead of asking, so run codex mcp login supadata if Supadata tools stop working in Codex.

Configuration

Environment Variables

• SUPADATA_API_KEY: Your Supadata API key (required for the stdio server). Get one at dash.supadata.ai
• DEBUG: set to true for verbose logging
• RUN_STDIO: set to true to force the stdio server to start when the module is imported rather than executed directly

How to Choose a Tool

Select the right tool based on your needs:

• Transcript: Extract video transcripts from platforms and file URLs
• Scrape: Extract content from a single page when you know the exact URL
• Map: Discover all available URLs on a website
• Crawl: Extract content from multiple related pages comprehensively
• Metadata: Fetch metadata from media URLs (YouTube, TikTok, Instagram, Twitter)
• Extract: Extract structured data from video content using AI

Tool	Best for	Returns
transcript	Video transcript extraction	text/markdown
metadata	Media metadata retrieval	JSON object
extract	AI-powered structured extraction	JSON object
scrape	Single page content	markdown/html
map	URL discovery on a site	URL[]
crawl	Multi-page extraction	markdown/html[]

Available Tools

Transcript (supadata_transcript)

Extract transcripts from supported video platforms (YouTube, TikTok, Instagram, Twitter) and file URLs.

Usage:

supadata_transcript --url "https://youtube.com/watch?v=example" --lang "en"

Check Transcript Status (supadata_check_transcript_status)

Check the progress of a transcript extraction job using the job ID.

Usage:

supadata_check_transcript_status --id "550e8400-e29b-41d4-a716-446655440000"

Metadata (supadata_metadata)

Fetch metadata from a media URL on supported platforms (YouTube, TikTok, Instagram, Twitter). Returns platform info, title, description, author details, engagement stats, media details, tags, and creation date.

Usage:

supadata_metadata --url "https://youtube.com/watch?v=example"

Extract (supadata_extract)

Extract structured data from a video URL using AI. Provide a prompt for what to extract, a JSON Schema for the output format, or both. Returns a job ID for async processing.

Usage:

supadata_extract --url "https://youtube.com/watch?v=example" --prompt "Extract the main topics discussed"

Check Extract Status (supadata_check_extract_status)

Check the progress of an extract job using the job ID.

Usage:

supadata_check_extract_status --id "550e8400-e29b-41d4-a716-446655440000"

Scrape (supadata_scrape)

Extract content from a single URL with advanced options.

Usage:

supadata_scrape --url "https://example.com" --lang "en"

Map (supadata_map)

Discover all indexed URLs on a website to find relevant pages before scraping.

Usage:

supadata_map --url "https://example.com"

Crawl (supadata_crawl)

Start an asynchronous crawl job to extract content from multiple pages on a site.

Usage:

supadata_crawl --url "https://example.com/blog" --limit 100

Check Crawl Status (supadata_check_crawl_status)

Check the progress of a crawl job using the job ID.

Usage:

supadata_check_crawl_status --id "550e8400-e29b-41d4-a716-446655440000"

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Contributing

1. Fork the repository
2. Create your feature branch
3. Run tests: npm test
4. Submit a pull request

License

MIT License - see LICENSE file for details