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

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
• 🖥️ Part 1: Standalone CLI Usage (No AI Needed)
  • Installation & Execution Options
  • Use Case 1: Single Photo Slideshow
  • Use Case 2: Single HD Video (MP4)
  • Use Case 3: Mobile Short Links (vm.tiktok.com)
  • Use Case 4: Bulk Profile Download (Everything)
  • Use Case 5: Bulk Profile - Photos Only
  • Use Case 6: Bulk Profile - Videos Only
  • Use Case 7: Custom Output Directory
  • CLI Flags Reference
• 🤖 Part 2: Model Context Protocol (MCP) Setup
  • AI Setup Guides (Claude Code, Desktop, Cursor, Windsurf, Antigravity)
  • MCP Tools & Natural Language Examples
• 📊 Metadata & Analytics Schemas
• 📁 Folder Hierarchy
• ❓ FAQ & Troubleshooting

---

✨ 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

---

📄 License

MIT © abdouldotdev