<div align="center">

# 🎵 TikTok MCP Server

### The first complete TikTok MCP server with publish, interact, and browse

**Search • Download • Publish • Like • Comment • Follow • Analyze Trends — all from your AI assistant.**

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)
[![GitHub Stars](https://img.shields.io/github/stars/follox42/tiktok-mcp?style=social)](https://github.com/follox42/tiktok-mcp)

<br/>

<img src="https://img.shields.io/badge/TikTok-000000?style=for-the-badge&logo=tiktok&logoColor=white" alt="TikTok"/>
<img src="https://img.shields.io/badge/Playwright-2EAD33?style=for-the-badge&logo=playwright&logoColor=white" alt="Playwright"/>
<img src="https://img.shields.io/badge/Claude-8A2BE2?style=for-the-badge" alt="Claude"/>

</div>

---

## ⚡ Why tiktok-mcp?

Most TikTok MCP servers only let you **read** data. This one lets you **act**.

- 🔍 **Browse** — Search videos, explore hashtags, scroll the For You Page
- 📥 **Download** — Save videos without watermark (HD when available)
- 📤 **Publish** — Upload videos directly to TikTok via Creator Center
- 💬 **Interact** — Like, comment, and follow — all automated
- 📊 **Analyze** — Cross-keyword trend analysis with top hashtags & creators

> **12 tools. One server. Full TikTok automation.**

---

## 🛠️ All 12 Tools

| Tool | Description |
|------|-------------|
| `tiktok_search` | Search TikTok videos by keyword. Returns author, description, views, URL, hashtags. |
| `tiktok_trending` | Get trending/For You videos from TikTok's main feed. |
| `tiktok_feed` | Scroll the For You Page like a real user and collect video metadata. |
| `tiktok_user_videos` | Get all videos from a specific user's profile with their stats. |
| `tiktok_video_info` | Get detailed metadata for a specific video (stats, audio, hashtags, description). |
| `tiktok_hashtag` | Explore a hashtag — view count, popular videos, and stats. |
| `tiktok_download` | Download a TikTok video without watermark (HD when available via tikwm). |
| `tiktok_publish` | **Publish a video** to TikTok with caption and hashtags via Creator Center. |
| `tiktok_interact` | **Like, comment, or follow** — interact with any video or creator. |
| `tiktok_sounds` | Get trending sounds/music on TikTok. |
| `tiktok_session` | Manage your TikTok session: check login, refresh cookies, export session. |
| `tiktok_analyze_trend` | Multi-keyword trend analysis: top hashtags, top creators, posting patterns. |

---

## 🚀 Installation (3 Steps)

### 1. Clone & Install

```bash
git clone https://github.com/follox42/tiktok-mcp.git
cd tiktok-mcp
pip install -e .
playwright install chromium
```

### 2. Get Your TikTok Cookies

You need authenticated cookies for publish/interact features. Two options:

**Option A — From TikSimPro (recommended):**
```bash
# If you use TikSimPro, cookies are already at:
~/TikSimPro/tiktok_cookies.pkl
```

**Option B — Export manually:**
1. Log into TikTok in your browser
2. Use a cookie export extension (e.g., "Get cookies.txt")
3. Save as JSON:
```json
[
  {"name": "sessionid", "value": "xxx", "domain": ".tiktok.com", "path": "/"},
  {"name": "sid_tt", "value": "xxx", "domain": ".tiktok.com", "path": "/"}
]
```

### 3. Set Environment Variables

```bash
export TIKTOK_COOKIES_PATH="/path/to/your/cookies.pkl"  # or .json
export TIKTOK_HEADLESS=true       # false to see the browser
export TIKTOK_MIN_INTERVAL=2.0    # rate limit between calls (seconds)
export TIKTOK_DOWNLOAD_DIR="./downloads"
```

---

## ⚙️ Configuration

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "tiktok": {
      "command": "tiktok-mcp",
      "env": {
        "TIKTOK_COOKIES_PATH": "/home/you/TikSimPro/tiktok_cookies.pkl",
        "TIKTOK_HEADLESS": "true"
      }
    }
  }
}
```

### mcporter

```json
{
  "servers": {
    "tiktok": {
      "command": "tiktok-mcp",
      "env": {
        "TIKTOK_COOKIES_PATH": "/home/you/TikSimPro/tiktok_cookies.pkl"
      }
    }
  }
}
```

### Direct (stdio)

```bash
tiktok-mcp
# or
python -m tiktok_mcp
```

---

## 📖 Usage Examples

### 🔍 Search Videos

```
Use tiktok_search to find "AI productivity" videos
```
```json
{"query": "AI productivity", "count": 10}
```

### 📊 Analyze a Niche

```
Analyze trends for "solopreneur" and "indie hacker" — what hashtags and creators dominate?
```
```json
{"keywords": ["solopreneur", "indie hacker", "build in public"], "count_per_keyword": 15}
```

### 👤 Research a Creator

```
Get the last 20 videos from @garyvee
```
```json
{"username": "garyvee", "count": 20}
```

### 📥 Download a Video

```
Download this video without watermark: https://www.tiktok.com/@user/video/123456
```
```json
{"video_url": "https://www.tiktok.com/@user/video/123456"}
```

### 📤 Publish a Video

```
Publish my video with caption "Building in public day 47 🚀" and hashtags buildinpublic, startup, coding
```
```json
{
  "video_path": "/path/to/video.mp4",
  "caption": "Building in public day 47 🚀",
  "hashtags": ["buildinpublic", "startup", "coding"]
}
```

### 💬 Interact (Like / Comment / Follow)

```
Like this video and leave a comment: "This is incredible! 🔥"
```
```json
{"action": "like", "video_url": "https://www.tiktok.com/@user/video/123456"}
{"action": "comment", "video_url": "https://www.tiktok.com/@user/video/123456", "text": "This is incredible! 🔥"}
{"action": "follow", "video_url": "https://www.tiktok.com/@user/video/123456"}
```

### 🎵 Trending Sounds

```
What sounds are trending on TikTok right now?
```
```json
{"count": 20}
```

### 🔐 Session Management

```
Check if my TikTok session is still active
```
```json
{"action": "check_login"}
{"action": "refresh_cookies"}
{"action": "export_session"}
```

---

## 🏆 Comparison — Why This One?

| Feature | **tiktok-mcp** | Other TikTok MCPs |
|---------|:--------------:|:------------------:|
| Search videos | ✅ | ✅ |
| Trending feed | ✅ | ⚠️ Some |
| User profiles | ✅ | ⚠️ Some |
| Video details | ✅ | ✅ |
| Hashtag exploration | ✅ | ❌ |
| Download (no watermark) | ✅ | ❌ |
| **Publish videos** | ✅ | ❌ |
| **Like / Comment / Follow** | ✅ | ❌ |
| Trending sounds | ✅ | ❌ |
| Trend analysis | ✅ | ❌ |
| Session management | ✅ | ❌ |
| Stealth / anti-detection | ✅ | ❌ |
| Cookie auth (TikSimPro) | ✅ | ❌ |
| **Total tools** | **12** | 2-4 |

> **tiktok-mcp is the only MCP server that lets you publish and interact on TikTok.**

---

## 📸 Demo

<!-- Add screenshots/GIFs here -->

<div align="center">
<i>Screenshots and demo GIFs coming soon.</i>

<!-- 
![Search Demo](assets/search-demo.gif)
![Publish Demo](assets/publish-demo.gif)
-->

</div>

---

## 🏗️ Built With

- **[Playwright](https://playwright.dev/)** — Browser automation with stealth capabilities
- **[playwright-stealth](https://github.com/nicedayzhu/playwright-stealth)** — Anti-detection patches
- **[MCP SDK](https://modelcontextprotocol.io)** — Model Context Protocol for AI integration
- **[TikSimPro](https://github.com/follox42/TikSimPro)** — Cookie management & TikTok session handling
- **[tikwm](https://tikwm.com)** — Watermark-free video downloads
- **[httpx](https://www.python-httpx.org/)** — Async HTTP client

---

## 🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Ideas for contributions:
- 📱 Mobile viewport support
- 🌍 Multi-language support
- 📊 Advanced analytics (engagement rate, best posting times)
- 🔄 Scheduled posting
- 🎭 Multiple account support

---

## 📄 License

This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

---

<div align="center">

**⭐ Star this repo if you find it useful!**

Made with ❤️ by [follox42](https://github.com/follox42)

</div>