tiktok-downloader-mcp
📱 TikTok Media Downloader & Analytics (CLI & MCP Server)
올인원 TikTok 추출 제품군: 터미널에서 독립형 CLI 도구(AI 불필요)로 직접 실행하거나, Model Context Protocol (MCP) 서버로 연결하여 AI 어시스턴트(Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity)와 함께 사용할 수 있습니다.
TikTok HD 동영상(.mp4) 및 원본 품질의 워터마크 없는 사진 슬라이드쇼/캐러셀을 추출, 분석 및 대량 다운로드하며, 구조화된 날짜 폴더(YYYY-MM-DD_<id>)로 정리하고 포괄적인 계정 참여 분석을 제공합니다.
📑 목차
Related MCP server: TikTok Complete MCP Server
✨ 주요 기능
⚡ 이중 실행: 터미널에서
npx로 직접 사용하거나 LLM과 함께 MCP 서버로 통합 가능.🎥 HD 워터마크 없는 동영상: 고해상도
.mp4동영상 파일과 원본 커버 썸네일 다운로드.📸 HD 워터마크 없는 사진: 최고 해상도의 원본 사진 및 캐러셀 슬라이드 추출.
📁 날짜 기반 정리: 모든 게시물이
YYYY-MM-DD_<id>/폴더에 저장됨.📊 풍부한 참여 분석:
총 조회수 (
play_count)총 좋아요 (
digg_count)총 댓글 (
comment_count)총 공유 (
share_count)총 즐겨찾기/저장 (
collect_count)총 다운로드 (
download_count)평균 참여율 (%)
최고 성과 게시물 (최다 조회, 최다 좋아요, 최다 공유, 최다 댓글)
📝 이중 레이어 JSON 요약:
계정 루트 디렉터리에
account_summary.json및account_activity.json.모든 게시물 폴더 내부에
post.json및account_activity_recap.json.
🚀 로그인/쿠키 불필요: 공개 TikTok 엔드포인트를 사용하여 즉시 작동.
🖥️ 1부: 독립형 CLI 사용법 (AI 불필요)
AI 어시스턴트나 설정 없이 터미널에서 다운로더를 실행할 수 있습니다.
설치 및 실행 옵션
# 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>사례 1: 단일 사진 슬라이드쇼
모든 슬라이드를 최고 해상도로 다운로드하고 메타데이터를 저장합니다:
npx tiktok-downloader-mcp "https://www.tiktok.com/@username/photo/7405928371928371234"생성된 구조:
tiktok_downloads/
└── username/
└── 2026-08-16_7405928371928371234/
├── slide_01.jpg
├── slide_02.jpg
├── slide_03.jpg
├── cover.jpg
└── post.json사례 2: 단일 HD 동영상 (MP4)
워터마크 없는 HD 동영상과 커버 썸네일을 다운로드합니다:
npx tiktok-downloader-mcp "https://www.tiktok.com/@username/video/7106594312292453675"생성된 구조:
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사례 3: 모바일 단축 링크 (vm.tiktok.com)
단축된 모바일 URL은 자동으로 해석됩니다:
npx tiktok-downloader-mcp "https://vm.tiktok.com/ZMhNxxxx/"사례 4: 프로필 대량 다운로드 (전체)
프로필을 스캔하여 사진과 동영상을 모두 다운로드하고 총 계정 참여 분석을 계산합니다:
# 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사례 5: 프로필 대량 - 사진만
독립형 동영상을 걸러내고 사진 슬라이드쇼/캐러셀만 다운로드합니다:
npx tiktok-downloader-mcp @username --media photos
# or:
npx tiktok-downloader-mcp @username --photos-only --max 30사례 6: 프로필 대량 - 동영상만
사진 슬라이드쇼를 걸러내고 HD MP4 동영상 게시물만 다운로드합니다:
npx tiktok-downloader-mcp @username --media videos
# or:
npx tiktok-downloader-mcp @username --videos-only --max 30사례 7: 사용자 지정 출력 디렉터리
파일을 저장할 위치를 지정합니다:
npx tiktok-downloader-mcp @username --out "/Users/me/Desktop/MyTikTokMedia"CLI 플래그 참조
플래그 | 값 | 기본값 | 설명 |
|
| 필수 | 프로필 사용자명, 프로필 URL 또는 직접 게시물 URL |
|
|
| 다운로드할 미디어 유형 필터 |
| - |
|
|
| - |
|
|
|
|
| 가져올 최대 게시물 수 |
|
|
| 시스템의 대상 출력 디렉터리 |
| - | - | 도움말 메뉴 표시 |
🤖 2부: Model Context Protocol (MCP) 설정
서버를 AI 어시스턴트에 연결하여 LLM이 자연어를 통해 TikTok 콘텐츠를 추출, 분석 및 다운로드하도록 합니다.
플랫폼별 MCP 설정
1. Claude Code CLI (권장)
# 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-mcpClaude Code 내에서 상태 확인:
/mcp2. Claude Desktop
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
.cursor/mcp.json 또는 프로젝트 .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 도구 참조
도구 | 목적 | 매개변수 | 자연어 예제 |
| 파일을 저장하지 않고 워터마크 없는 미디어 URL, 오디오 및 측정항목을 추출합니다. |
| "이 링크에서 이미지, 오디오 및 조회수를 추출해 줘: https://www.tiktok.com/@user/photo/123" |
| 프로필의 최근 게시물 ID, 업로드 날짜 및 URL을 나열합니다. |
| "@username이 게시한 최근 15개 게시물을 날짜와 함께 나열해 줘." |
| 단일 게시물(사진 또는 동영상)을 날짜 폴더에 |
| "이 TikTok 동영상을 내 다운로드 폴더에 HD로 다운로드해 줘." |
| 동영상/사진을 날짜 폴더에 대량 다운로드하고 전역 |
| "@username의 모든 사진 캐러셀을 다운로드하고 참여도를 요약해 줘." |
| 파일을 다운로드하지 않고 계정 총계, 평균, 참여율 및 최고 게시물을 계산합니다. |
| "@username의 참여율과 최고 성과 게시물을 분석해 줘." |
📊 메타데이터 및 분석 스키마
1. account_summary.json (계정 수준)
사용자 폴더 루트(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 (게시물 수준)
각 개별 게시물 폴더 내부(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 }
}
}📁 폴더 계층 구조
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 및 문제 해결
Q: 이 도구를 사용하려면 TikTok 계정이나 쿠키가 필요한가요?
A: 아니요. 모든 다운로드 및 메타데이터 추출은 공개 엔드포인트를 사용하여 로그인이나 세션 쿠키 없이 즉시 작동합니다.
Q: 다운로드된 동영상과 이미지에 워터마크가 있나요?
A: 아니요. 다운로드된 모든 미디어 파일은 TikTok의 튀는 워터마크가 없는 깨끗한 원본 품질의 파일입니다.
Q: 명령을 다시 실행하면 기존 파일을 다시 다운로드하나요?
A: 아니요. 도구는 디스크에 있는 파일 크기와 존재 여부를 확인합니다. 슬라이드나 동영상이 이미 다운로드된 경우 자동으로 건너뛰어 즉시 속도를 냅니다.
Q: 어떤 종속성이 필요한가요?
A: Node.js >= 18이 필요합니다. 프로필 스캔을 위해 yt-dlp가 권장됩니다(macOS에서는 brew install yt-dlp, 또는 pip install yt-dlp).
💻 로컬 개발 및 기여
# 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📄 라이선스
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.-