📱 TikTok Media Downloader & Analytics (CLI & MCP Server)

npm version License: MIT

All-in-one TikTok extraction suite: Run it directly from your terminal as a Standalone CLI tool (no AI required) or connect it as a Model Context Protocol (MCP) Server for AI assistants (Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity).

Extract, analyze, and bulk-download TikTok HD videos (.mp4) and photo slideshows/carousels in original quality without watermarks, organized into structured date folders (YYYY-MM-DD_<id>) with comprehensive account engagement analytics.

📑 Table of Contents

✨ Key Features

⚡ Dual Execution: Use directly in your terminal via npx or integrate as an MCP server with LLMs.
🎥 HD No-Watermark Videos: Download high-resolution .mp4 video files with original cover thumbnails.
📸 HD No-Watermark Photos: Extract full-resolution original photos and carousel slides.
📁 Date-Based Organization: Every post is filed under YYYY-MM-DD_<id>/.
📊 Rich Engagement Analytics:
- Total Views (play_count)
- Total Likes (digg_count)
- Total Comments (comment_count)
- Total Shares (share_count)
- Total Favorites / Saves (collect_count)
- Total Downloads (download_count)
- Average Engagement Rate (%)
- Top Performing Posts (Most viewed, most liked, most shared, most commented)
📝 Dual-Layer JSON Summaries:
- account_summary.json & account_activity.json in the root account directory.
- post.json & account_activity_recap.json inside every single post folder.
🚀 Zero Login / Cookies Needed: Works seamlessly out of the box with public TikTok endpoints.

🖥️ Part 1: Standalone CLI Usage (No AI Needed)

You can run the downloader in your terminal without any AI assistant or configuration.

Installation & Execution Options

# Option A: One-liner via NPX (No installation needed)
npx tiktok-downloader-mcp <arguments>

# Option B: Global NPM install
npm install -g tiktok-downloader-mcp
tiktok-downloader-mcp <arguments>

# Option C: Local Git Clone
git clone https://github.com/abdouldotdev/tiktok-downloader-mcp.git
cd tiktok-downloader-mcp && npm install && npm run build
node dist/index.js <arguments>

Case 1: Single Photo Slideshow

Downloads all slides in full resolution and saves metadata:

npx tiktok-downloader-mcp "https://www.tiktok.com/@username/photo/7405928371928371234"

Generated structure:

tiktok_downloads/
  └── username/
      └── 2026-08-16_7405928371928371234/
          ├── slide_01.jpg
          ├── slide_02.jpg
          ├── slide_03.jpg
          ├── cover.jpg
          └── post.json

Case 2: Single HD Video (MP4)

Downloads the unwatermarked HD video and its cover thumbnail:

npx tiktok-downloader-mcp "https://www.tiktok.com/@username/video/7106594312292453675"

Generated structure:

tiktok_downloads/
  └── username/
      └── 2026-08-15_7106594312292453675/
          ├── video.mp4     # Clean HD video without watermark
          ├── cover.jpg     # Video thumbnail
          └── post.json     # Views, likes, comments, sound metadata

Case 3: Mobile Short Links (`vm.tiktok.com`)

Shortened mobile URLs are automatically resolved:

npx tiktok-downloader-mcp "https://vm.tiktok.com/ZMhNxxxx/"

Case 4: Bulk Profile Download (Everything)

Scans a profile, downloads both photos and videos, and computes total account engagement analytics:

# Download recent 50 posts (default):
npx tiktok-downloader-mcp @username

# Download recent 20 posts:
npx tiktok-downloader-mcp @username --max 20

# Download ALL posts from the profile:
npx tiktok-downloader-mcp @username --max all

Case 5: Bulk Profile - Photos Only

Filters out standalone videos and downloads only photo slideshows / carousels:

npx tiktok-downloader-mcp @username --media photos
# or:
npx tiktok-downloader-mcp @username --photos-only --max 30

Case 6: Bulk Profile - Videos Only

Filters out photo slideshows and downloads only HD MP4 video posts:

npx tiktok-downloader-mcp @username --media videos
# or:
npx tiktok-downloader-mcp @username --videos-only --max 30

Case 7: Custom Output Directory

Specify where files should be stored:

npx tiktok-downloader-mcp @username --out "/Users/me/Desktop/MyTikTokMedia"

CLI Flags Reference

Flag	Values	Default	Description
`<target>`	`@username` \| `url`	Required	Profile username, profile URL, or direct post URL
`--media`	`all` \| `photos` \| `videos`	`all`	Filter media types to download
`--photos-only`	-	`false`	Shortcut for `--media photos`
`--videos-only`	-	`false`	Shortcut for `--media videos`
`--max`	`number` \| `all`	`50`	Maximum number of posts to fetch
`--out`	`path`	`./tiktok_downloads`	Target output directory on your system
`--help`, `-h`	-	-	Display help menu

🤖 Part 2: Model Context Protocol (MCP) Setup

Connect the server to an AI assistant to let the LLM extract, analyze, and download TikTok content for you via natural language.

MCP Configuration by Platform

1. Claude Code CLI (Recommended)

# Add via NPX:
claude mcp add tiktok-downloader -- npx -y tiktok-downloader-mcp

# Or directly from GitHub:
claude mcp add tiktok-downloader -- npx -y github:abdouldotdev/tiktok-downloader-mcp

Check status inside Claude Code:

/mcp

2. Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tiktok-downloader": {
      "command": "npx",
      "args": ["-y", "tiktok-downloader-mcp"]
    }
  }
}

3. Cursor & Windsurf

Add to .cursor/mcp.json or project .mcp.json:

{
  "mcpServers": {
    "tiktok-downloader": {
      "command": "npx",
      "args": ["-y", "tiktok-downloader-mcp"]
    }
  }
}

4. Antigravity CLI

agy mcp add tiktok-downloader -- npx -y tiktok-downloader-mcp

MCP Tools Reference

Tool	Purpose	Parameters	Natural Language Example
`tiktok_extract_post`	Extracts unwatermarked media URLs, audio, and metrics without saving files.	`url` (string)	"Extract the images, audio, and view count from this link: https://www.tiktok.com/@user/photo/123"
`tiktok_get_user_posts`	Lists recent post IDs, upload dates, and URLs for a profile.	`username` (string), `max` (number)	"List the last 15 posts published by @username with their dates."
`tiktok_download_post`	Downloads a single post (photos or video) to a date folder with `post.json`.	`url` (string), `output_dir` (string)	"Download this TikTok video in HD to my downloads folder."
`tiktok_download_user_media`	Bulk downloads videos/photos into date folders and creates global `account_summary.json`.	`username` (string), `max` (number), `output_dir` (string), `media_type` (`"all"\|"photos"\|"videos"`)	"Download all photo carousels from @username and summarize their engagement."
`tiktok_get_user_analytics`	Computes account totals, averages, engagement rate, and top posts without downloading files.	`username` (string), `max` (number)	"Analyze the engagement rate and top performing posts of @username."

📊 Metadata & Analytics Schemas

1. `account_summary.json` (Account Level)

Saved at the root of the user folder (tiktok_downloads/<username>/account_summary.json):

{
  "account": {
    "username": "example_user",
    "nickname": "Creator Name",
    "user_id": "7582772389835113485",
    "avatar": "https://.../avatar.jpeg",
    "profile_url": "https://www.tiktok.com/@example_user"
  },
  "activity_totals": {
    "total_posts_analyzed": 50,
    "total_slideshows_count": 32,
    "total_videos_count": 18,
    "total_images_count": 312,
    "total_views": 1066188,
    "total_likes": 17388,
    "total_comments": 6078,
    "total_shares": 410,
    "total_favorites_saves": 2579,
    "total_downloads": 74,
    "total_all_interactions": 26455
  },
  "performance_averages": {
    "avg_views_per_post": 21324,
    "avg_likes_per_post": 348,
    "avg_comments_per_post": 121.6,
    "avg_shares_per_post": 8.2,
    "avg_favorites_per_post": 51.6,
    "avg_engagement_rate_percent": 2.48
  },
  "top_performing_posts": {
    "most_viewed": { "id": "7652520719259159822", "date": "2026-06-18", "views": 461748, "type": "slideshow" },
    "most_liked": { "id": "7652520719259159822", "date": "2026-06-18", "likes": 5558, "type": "slideshow" }
  },
  "updated_at": "2026-08-18T15:57:52.024Z"
}

2. `post.json` (Post Level)

Saved inside each individual post folder (tiktok_downloads/<username>/YYYY-MM-DD_<id>/post.json):

{
  "post_details": {
    "id": "7674774636999003406",
    "user": "example_user",
    "author": { "uniqueId": "example_user", "nickname": "Creator Name" },
    "title": "Summer outfit ideas #fashion #summer",
    "media_type": "slideshow",
    "date": "2026-08-16",
    "timestamp": 1787049600,
    "url": "https://www.tiktok.com/@example_user/video/7674774636999003406",
    "slides_count": 10,
    "stats": {
      "views": 1120,
      "likes": 21,
      "comments": 17,
      "shares": 1,
      "favorites": 5,
      "downloads": 0,
      "total_interactions": 44,
      "engagement_rate_percent": 3.93
    },
    "music": {
      "id": "7644346595656730640",
      "title": "Original Sound",
      "author": "Sound Creator",
      "duration": 60,
      "play_url": "https://.../audio.mp4"
    }
  },
  "account_recap": {
    "username": "example_user",
    "activity_totals": { "total_views": 1066188, "total_likes": 17388 },
    "performance_averages": { "avg_engagement_rate_percent": 2.48 }
  }
}

📁 Folder Hierarchy

tiktok_downloads/
  └── example_user/
      ├── account_summary.json            # Cumulative totals, averages, engagement & top posts
      ├── account_activity.json           # Complete chronological history of all posts
      │
      ├── 2026-08-16_7674774636999003406/ # 📸 Photo Slideshow post folder
      │   ├── slide_01.jpg
      │   ├── slide_02.jpg
      │   ├── slide_03.jpg
      │   ├── cover.jpg
      │   ├── post.json                   # Individual post metrics + global account recap
      │   └── account_activity_recap.json
      │
      └── 2026-08-15_7674392602606619917/ # 🎬 Video post folder
          ├── video.mp4                   # HD unwatermarked video
          ├── cover.jpg                   # Video cover thumbnail
          ├── post.json
          └── account_activity_recap.json

❓ FAQ & Troubleshooting

Q: Do I need a TikTok account or cookies to use this?

A: No. All downloads and metadata extractions work out of the box using public endpoints without any login or session cookies.

Q: Are downloaded videos and images watermarked?

A: No. 100% of the downloaded media files are clean, original-quality files without the TikTok bouncing watermark.

Q: Does it re-download existing files if I re-run the command?

A: No. The tool checks file size and presence on disk. If a slide or video has already been downloaded, it will automatically skip it for instant speed.

Q: What dependencies are needed?

A: Node.js >= 18. For profile scanning, yt-dlp is recommended (brew install yt-dlp on macOS or pip install yt-dlp).

💻 Local Development & Contributions

# Clone repository
git clone https://github.com/abdouldotdev/tiktok-downloader-mcp.git
cd tiktok-downloader-mcp

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run CLI locally
node dist/index.js @username --max 10

# Run MCP Server on stdio
node dist/index.js --stdio

tiktok-downloader-mcp

📱 TikTok Media Downloader & Analytics (CLI & MCP Server)

📑 Table of Contents

✨ Key Features

🖥️ Part 1: Standalone CLI Usage (No AI Needed)

Installation & Execution Options

Case 1: Single Photo Slideshow

Case 2: Single HD Video (MP4)

Case 3: Mobile Short Links (`vm.tiktok.com`)

Case 4: Bulk Profile Download (Everything)

Case 5: Bulk Profile - Photos Only

Case 6: Bulk Profile - Videos Only

Case 7: Custom Output Directory

CLI Flags Reference

🤖 Part 2: Model Context Protocol (MCP) Setup

MCP Configuration by Platform

1. Claude Code CLI (Recommended)

2. Claude Desktop

3. Cursor & Windsurf

4. Antigravity CLI

MCP Tools Reference

📊 Metadata & Analytics Schemas

1. `account_summary.json` (Account Level)

2. `post.json` (Post Level)

📁 Folder Hierarchy

❓ FAQ & Troubleshooting

Q: Do I need a TikTok account or cookies to use this?

Q: Are downloaded videos and images watermarked?

Q: Does it re-download existing files if I re-run the command?

Q: What dependencies are needed?

💻 Local Development & Contributions

📄 License

Latest Blog Posts

MCP directory API

📱 TikTok Media Downloader & Analytics (CLI & MCP Server)

📑 Table of Contents

✨ Key Features

🖥️ Part 1: Standalone CLI Usage (No AI Needed)

Installation & Execution Options

Case 1: Single Photo Slideshow

Case 2: Single HD Video (MP4)

Case 3: Mobile Short Links (vm.tiktok.com)

Case 4: Bulk Profile Download (Everything)

Case 5: Bulk Profile - Photos Only

Case 6: Bulk Profile - Videos Only

Case 7: Custom Output Directory

CLI Flags Reference

🤖 Part 2: Model Context Protocol (MCP) Setup

MCP Configuration by Platform

1. Claude Code CLI (Recommended)

2. Claude Desktop

3. Cursor & Windsurf

4. Antigravity CLI

MCP Tools Reference

📊 Metadata & Analytics Schemas

1. account_summary.json (Account Level)

2. post.json (Post Level)

📁 Folder Hierarchy

❓ FAQ & Troubleshooting

Q: Do I need a TikTok account or cookies to use this?

Q: Are downloaded videos and images watermarked?

Q: Does it re-download existing files if I re-run the command?

Q: What dependencies are needed?

💻 Local Development & Contributions

📄 License

Latest Blog Posts

MCP directory API

Case 3: Mobile Short Links (`vm.tiktok.com`)

1. `account_summary.json` (Account Level)

2. `post.json` (Post Level)