tiktok-downloader-mcp
Provides tools for extracting, analyzing, and downloading TikTok content including HD no-watermark videos and photo slideshows, with support for single posts, mobile short links, and bulk profile downloads organized into date-based folders with comprehensive engagement analytics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tiktok-downloader-mcp download the TikTok video from https://vm.tiktok.com/abc123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π± 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
Related MCP server: TikTok Complete MCP Server
β¨ Key Features
β‘ Dual Execution: Use directly in your terminal via
npxor integrate as an MCP server with LLMs.π₯ HD No-Watermark Videos: Download high-resolution
.mp4video 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.jsonin the root account directory.post.json&account_activity_recap.jsoninside 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.jsonCase 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 metadataCase 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 allCase 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 30Case 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 30Case 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 |
|
| Required | Profile username, profile URL, or direct post URL |
|
|
| Filter media types to download |
| - |
| Shortcut for |
| - |
| Shortcut for |
|
|
| Maximum number of posts to fetch |
|
|
| Target output directory on your system |
| - | - | 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-mcpCheck status inside Claude Code:
/mcp2. Claude Desktop
Add to your claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%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-mcpMCP Tools Reference
Tool | Purpose | Parameters | Natural Language Example |
| Extracts unwatermarked media URLs, audio, and metrics without saving files. |
| "Extract the images, audio, and view count from this link: https://www.tiktok.com/@user/photo/123" |
| Lists recent post IDs, upload dates, and URLs for a profile. |
| "List the last 15 posts published by @username with their dates." |
| Downloads a single post (photos or video) to a date folder with |
| "Download this TikTok video in HD to my downloads folder." |
| Bulk downloads videos/photos into date folders and creates global |
| "Download all photo carousels from @username and summarize their engagement." |
| Computes account totals, averages, engagement rate, and top posts without downloading files. |
| "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
Available Tools
5 toolstiktok_download_postA
Download a TikTok post (unwatermarked HD MP4 video or photo slides) into a date-named folder (YYYY-MM-DD_) with full post.json metadata.
Inputs: url (required), output_dir.
tiktok_download_user_mediaA
Download all media (photos slideshows and/or HD MP4 videos) from a TikTok account into organized date folders (YYYY-MM-DD_), with post.json in each folder and full account_summary.json.
Inputs: username (required), max, media_type, output_dir.
tiktok_extract_postA
Extract unwatermarked HD photos, video download URL, audio, and full engagement metrics (views, likes, comments, shares, saves) from any TikTok URL.
Inputs: url (required).
tiktok_get_user_analyticsB
Analyze a TikTok profile's recent engagement metrics, total views, likes, comments, shares, engagement rate, and top performing posts without downloading files.
Inputs: username (required), max.
tiktok_get_user_postsB
List recent post IDs, upload dates, and URLs for a TikTok user or profile URL.
Inputs: username (required), max.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 5 tools
Each tool has a clear, distinct purpose: extracting post info, listing user posts, downloading a single post, downloading all user media, and getting user analytics. No significant overlap between any two tools.
All tools follow the pattern 'tiktok_<verb>_<object>', with verbs like extract, get, download. The pattern is consistent, though 'extract' vs 'get' for similar retrieval operations is a minor inconsistency.
Five tools is well-scoped for a TikTok downloader: essential operations for data extraction, listing, downloading, and analytics are covered without bloat.
The surface covers the core workflow: obtain URLs, list posts, download individual or all user media, and analyze engagement. Missing features like search or hashtag downloads are beyond the stated scope, so minor gap.
Maintenance
Related MCP Connectors
Real-time TikTok profile, video feed, comments, search & HD media metadata API for AI agents.
Public TikTok profiles, videos, comments and keyword search as JSON. No developer account.
Real-time TikTok videos, profiles, comments, trends & Creative Center ads MCP. OAuth or API key.
TikTok research for AI agents. Ask ChatGPT, Claude, Cursor, Codex or any MCP client what people search, watch, say and buy on TikTok, and get real numbers back. 34 tools: weekly TikTok search volume and 7-day trends, content gaps, videos, creators, comments and caption transcripts, hashtags and sounds, TikTok Shop sales estimates for products, shops, creators, videos and LIVE streams, TikTokβs Top Ads library with CTR and retention, places, and a fair comment-giveaway picker. 17 markets. Built for marketers, agencies, TikTok Shop sellers and creators. Sign in with OAuth or an API key; 50 free credits, no card.
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceA comprehensive MCP server that enables AI assistants to search, download, and analyze TikTok content while also performing active tasks like publishing videos and interacting with posts. It provides full automation capabilities for TikTok through browser session management and anti-detection features.122MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to download TikTok videos without watermarks, analyze creator metrics and audience insights, track trending content and hashtags, and search videos, users, and sounds through RapidAPI integration.-
- AlicenseAqualityCmaintenanceTikTok creator toolkit for AI assistants. Four tools: download watermark-free videos by URL, look up curated 15-hashtag sets for 15 niches with strategy tips, retrieve best posting times for 12 countries, and generate viral hook formulas across 8 categories. Stdio transport, runs via npx -y tiktapdown-mcp, no API keys, no signup, free. MIT license.1082 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables reading TikTok trends, profiles, comments, and own-account metrics via an unofficial facade with fallback providers and risk-tiered tools, plus queued posting capabilities.-