Content
<div align="center">
<h1>douyin-mcp</h1>
<p><strong>Let AI understand your Douyin creation data</strong></p>
<p>Local operation · Traceable data · MCP Server for personal creators</p>
<p>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+"></a>
<img src="https://img.shields.io/badge/Platform-Windows-0078D4?logo=windows11&logoColor=white" alt="Windows">
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Compatible-22C55E" alt="MCP Compatible"></a>
<a href="https://github.com/jlowin/fastmcp"><img src="https://img.shields.io/badge/FastMCP-Powered-FF6B35" alt="FastMCP Powered"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-8B5CF6" alt="AGPL-3.0"></a>
<a href="https://github.com/Kuhakucai/douyin-mcp/stargazers"><img src="https://img.shields.io/github/stars/Kuhakucai/douyin-mcp?style=flat&logo=github&label=Stars" alt="GitHub Stars"></a>
</p>
<p>
<a href="#快速开始">Quick Start</a> ·
<a href="#核心能力">Core Capabilities</a> ·
<a href="#推荐用法">Recommended Usage</a> ·
<a href="#mcp-工具">MCP Tools</a> ·
<a href="#工作原理">Working Principle</a> ·
<a href="#安全合规与许可">Security Compliance</a>
</p>
</div>
> [!IMPORTANT]
> **This is a non-official community tool.** This project is not authorized, recognized, or endorsed by Douyin or its affiliates. The project uses Playwright to operate the browser; even if only reading data visible in your own account, it may still violate platform terms or trigger account risk control. Please read the [Platform Compliance and Non-official Statement](PLATFORM_COMPLIANCE.md) before use, confirm you have obtained the required authorization, and execute risk confirmation first. AGPL only licenses the project code, not granting any platform access rights, data rights, or trademark rights.
## One-Minute Understanding
`douyin-mcp` replicates a dedicated Chrome login state on your computer, saving visible works and operational indicators from the Douyin Creator Center page to local SQLite, and then provides them to MCP-supported AI Agents.
| | |
|---|---|
| 📊 **Read real visible data**<br>Incrementally synchronize works list, playback, likes, comments, shares, collections, completion rate, and fan growth. | 🧠 **Let Agent query and analyze**<br>Query works, compare performance, calculate interaction indicators, generate review context, and export JSON or CSV. |
| 🧾 **Conclusion with evidence**<br>Return collection time, cache freshness, field coverage, missing reasons, and quality warnings, without guessing values. | 🔒 **Login credentials stay local**<br>Cookie and browser state are saved in a dedicated profile, and MCP does not return authentication materials to the Agent. |
It solves a specific problem:
```text
Douyin Creator Center → Local structured data → MCP → AI Agent
```
Current scope is **Windows, local operation, single user, single Douyin account**. This project does not provide multi-account hosting, cloud collection, data resale, or access to unpublicized interfaces, or bypass login, security verification, permissions, and risk control.
## Quick Start
### Environment Requirements
- Windows 10/11
- Python 3.11 or higher
- Google Chrome
- An Agent that supports MCP and terminal operations
### Method 1: Let Agent Install
Directly tell the Agent:
```text
Help me clone and install https://github.com/Kuhakucai/douyin-mcp project
```
The Agent should clone the project and run `easy-install.ps1`. The script creates a project-specific `.venv`, installs dependencies, generates a default `.env`, initializes the database, and performs environment diagnostics.
> [!NOTE]
> Before the first scan code login, modify MCP client configuration, or synchronize real data, the Agent should display platform risks and obtain your explicit confirmation.
### Method 2: Manual Installation
<details>
<summary><strong>Expand to view PowerShell installation commands</strong></summary>
```powershell
git clone https://github.com/Kuhakucai/douyin-mcp.git
cd douyin-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
Copy-Item .env.example .env
douyin-mcp init
douyin-mcp doctor
```
You can also run the one-click script in the cloned project:
```powershell
powershell -ExecutionPolicy Bypass -File .\easy-install.ps1
```
</details>
### Confirm Platform Risk
After reading [PLATFORM_COMPLIANCE.md](PLATFORM_COMPLIANCE.md), authorize the Agent to execute:
```powershell
douyin-mcp acknowledge-platform-risk --yes
```
### Access MCP Client
After installation, `douyin-mcp init` outputs `mcp_config` with a local absolute path. Add it to the MCP client and restart the client or create a new session.
The general configuration structure is as follows, and the actual use should be based on the output of `init`:
```json
{
"mcpServers": {
"douyin-creator": {
"command": "D:/path/to/douyin-mcp/.venv/Scripts/python.exe",
"args": ["-m", "douyin_creator_mcp.server"],
"env": {
"MCP_TRANSPORT": "stdio",
"DATA_DIR": "D:/path/to/douyin-mcp/data",
"DOUYIN_BROWSER_PROFILE_DIR": "D:/path/to/douyin-mcp/data/browser-profile"
}
}
}
}
```
### Complete First Synchronization
After successful connection and risk confirmation, you can directly tell the Agent:
```text
Check my Douyin data status. If not logged in, open the browser for me to scan code;
After logging in, synchronize the works list and then synchronize the details of the last 20 works in batches.
After completion, tell me data time, field coverage, missing items, and quality warnings.
```
The browser will open for the first login. Keep the project-specific Chrome open; you can switch to other software but do not switch accounts, manually jump pages, or close the window.
## Core Capabilities
### Obtain Real Visible Data
- Open visible Chrome for the first use or login failure, allowing the user to scan code or complete security verification.
- Reuse the project-specific browser profile for subsequent use, usually without repeated login.
- Incrementally read virtual scrolling works list, saving playback, likes, comments, shares, and collection indicators visible on the page.
- Read work details in batches as needed, collecting completion rate, 5-second completion rate, average viewing time, exposure, and fan growth indicators visible on the page.
### Query, Compare, and Review
- Query works list, single work performance, and historical snapshots.
- Compare key indicators of 2-20 works.
- Calculate like rate, collection rate, comment rate, share rate, playback rate, and interaction rate.
- Perform lightweight potential sorting using transparent and versioned rules.
- Generate review context with data time, coverage, missing items, and evidence references.
- Export JSON or CSV for further analysis or backup.
### Verify Conclusion Reliability
- Return cache freshness, field coverage, missing reasons, and quality warnings.
- Values not displayed on the page are saved as `null`, not filled with 0 or guessed values.
- List and details are saved as snapshots, not mixing data sources.
- Derived ratios use the numerator and denominator from the same original snapshot and record the formula version.
- After the first successful synchronization, bind the current account and refuse to write when detecting account changes.
## Recommended Usage
Daily use, suggest checking cache freshness first, then decide whether to open the browser for synchronization:
```text
Check my Douyin data status. Update works list and recent 20 work details only when cache expires;
Then give a review conclusion based on the interaction rate, 5-second completion rate, and completion rate in the last 30 days, explaining data time, coverage, missing items, and work evidence.
```
You can also directly ask specific questions:
- “Find the top 5 works with the highest interaction rate in the last 30 days and explain common points.”
- “Compare the completion rate, collection rate, and fan growth performance of these 3 works.”
- “Which works are worth making a sequel? Explain sorting basis and data limitations.”
- “Export all historical snapshots as JSON.”
## CLI
Common commands:
```powershell
# First login or login failure
douyin-mcp login --timeout 180
# Synchronize works list
douyin-mcp sync
# View works and get video_id
douyin-mcp videos --limit 20
# Each batch processes up to 10 works; continue based on next_cursor
douyin-mcp details --recent-limit 20
douyin-mcp details --recent-limit 20 --cursor 10
# Query single work performance
douyin-mcp performance <video_id> --period 30d
# View login, cache, tasks, and coverage
douyin-mcp status
```
<details>
<summary><strong>View complete CLI command table</strong></summary>
| Command | Purpose |
|---|---|
| `init` | Initialize directory and database, output MCP configuration |
| `doctor` | Check running environment, do not open browser |
| `acknowledge-platform-risk` | Confirm reading and understanding platform automation access risks |
| `login` | Open browser and wait for login |
| `status` | View login, cache, synchronization tasks, and coverage |
| `sync` | Synchronize works list and list page indicators |
| `details` | Synchronize specified or recent work details in batches |
| `videos` | Paginate query local works |
| `performance` | Query single work snapshot and derived indicators |
| `export` | Export JSON or CSV |
| `purge` | Clear local data and dedicated browser profile |
</details>
## MCP Tools
The default entry provides 13 browser data tools.
<details open>
<summary><strong>View MCP tool list</strong></summary>
| Tool | Purpose |
|---|---|
| `douyin_browser_login_start` | Open visible Chrome, handle first login or re-login |
| `douyin_browser_login_status` | Query current browser login status |
| `douyin_browser_get_status` | Query freshness, tasks, coverage, account binding, and profile lock |
| `douyin_browser_sync_if_needed` | Synchronize list, details, or all data based on TTL |
| `douyin_browser_sync_creator_data` | Synchronize works list and list indicators |
| `douyin_browser_sync_video_details` | Synchronize specified or recent work details indicators in batches |
| `douyin_browser_list_videos` | Paginate query works and latest indicators |
| `douyin_browser_get_video_performance` | Query single work snapshot and derived indicators |
| `douyin_browser_compare_videos` | Compare 2-20 works |
| `douyin_browser_get_metric_coverage` | Query field coverage and missing reasons |
| `douyin_browser_rank_video_potential` | Lightweight sorting using transparent and versioned rules |
| `douyin_browser_generate_review` | Generate review context with evidence and warnings |
| `douyin_browser_export_data` | Export JSON or CSV |
</details>
All tools use the internal account key `browser-default`, and the Agent does not need to pass the account ID. Common business states include `completed`, `partial`, `cache_hit`, and `user_action_required`.
## Working Principle
Browser operation, data structuring, and Agent reasoning are divided into three clear levels:
1. **Browser Level**: Playwright operates the project-specific Chrome, reading content visible to users on the Creator Center page, without bypassing login, permissions, or platform verification.
2. **Data Level**: Local service standardizes page content into work, indicator snapshots, synchronization tasks, and quality status, and saves them to local SQLite.
3. **MCP Level**: FastMCP exposes synchronization, query, comparison, and review tools, and the Agent does not need to directly operate Cookie or understand page DOM.
```text
MCP Client / Agent
│ stdio
▼
douyin_creator_mcp.server
│
├── BrowserService ── Playwright ── dedicated Chrome profile
│
└── Database ──────── data/douyin.sqlite
```
List synchronization is responsible for discovering works and collecting list page indicators, and detail synchronization accesses work detail pages in batches. Two sources are saved as snapshots and will not overwrite each other.
### Data Reliability
- What is displayed on the page is saved; values not displayed are `null`, not filled with 0 or guessed values.
- Verify work identity before writing details; refuse to write if unable to confirm.
- Only one snapshot is written for the same batch, same work, and same source; failed synchronization will not overwrite historical trusted snapshots.
- `period=30d` and other cycles are filtered based on snapshot collection time; `all` represents all local history.
- Some works may be marked by the platform as temporarily not supporting detail data, returning `partial`, failure reasons, and continuation cursor at this time.
- Potential sorting is for reference only when the sample is less than 10 works and does not represent the official platform score.
- Page DOM, field visibility, and risk control strategies may change; use coverage and quality warnings during use.
### Login Status, Account, and Concurrency
- Login status is saved in `data/browser-profile/`, usually no need to scan code again after restarting.
- The first successful list synchronization will establish an irreversible account fingerprint based on work titles and release time, without saving nickname, original title, or work ID as identity information.
- Detect account changes and return `account_mismatch` and refuse to write.
- Only one synchronization process is allowed for the same profile at the same time; the zombie process left lock will automatically recover after security confirmation.
- Confirm to change accounts, run `douyin-mcp purge --yes`, then log in and synchronize.
### Local Data and Privacy
```text
data/
├── browser-profile/ # dedicated Chrome login status
├── douyin.sqlite # work, indicator snapshots, and synchronization tasks
├── exports/ # JSON/CSV export
├── reports/ # local review output
└── logs/
```
The above directories, database, backup, and browser diagnosis products are all excluded by `.gitignore`, please do not use `git add -f` submit.
MCP will not return Cookie, `localStorage`, `sessionStorage`, verification code, or account password to the Agent. However, work information and creation data you actively query will enter the Agent context; if the Agent uses cloud-end models, it should also comply with the data policy of the corresponding model service.
Export and clear:
```powershell
douyin-mcp export --format json --period all
douyin-mcp export --format csv --period 30d
# Without --yes, only display confirmation prompts
douyin-mcp purge
douyin-mcp purge --yes
```
> [!CAUTION]
> `purge --yes` will delete the database, database backup, export, report, and dedicated browser profile, and this operation is irreversible.
## FAQs
<details>
<summary><strong>PowerShell cannot find <code>douyin-mcp</code></strong></summary>
Activate virtual environment:
```powershell
.\.venv\Scripts\Activate.ps1
```
Or run directly:
```powershell
.\.venv\Scripts\douyin-mcp.exe doctor
```
</details>
<details>
<summary><strong>PowerShell prevents script installation</strong></summary>
The execution policy only applies to this command:
```powershell
powershell -ExecutionPolicy Bypass -File .\easy-install.ps1
```
</details>
<details>
<summary><strong>After login, still prompted to operate</strong></summary>
Keep the project-specific Chrome open, complete scan code, verification code, or security verification, and try synchronization again. Do not use the daily Chrome profile to replace the project-specific profile.</details>
<details>
<summary><strong>Return <code>profile_in_use</code></strong></summary>
Another synchronization process is still using the dedicated browser. Wait for it to end and try again; if the original process has exited, the lock will automatically recover after security confirmation.</details>
<details>
<summary><strong>Detail synchronization returns <code>partial</code></summary>
View `failures`, `coverage`, and `next_cursor`. Common reasons include works temporarily not supporting detail data, pages not displaying certain indicators, or the current batch still needs to continue.</details>
## Developer Guide
<details>
<summary><strong>Expand development environment, project structure, and acceptance instructions</strong></summary>
### Development Environment
```powershell
git clone https://github.com/Kuhakucai/douyin-mcp.git
cd douyin-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
python -m pip install pytest
Copy-Item .env.example .env
```
### Project Structure
```text
src/douyin_creator_mcp/
├── server.py # FastMCP entry and browser-only container
├── cli.py # User CLI
├── config.py # Environment configuration
├── browser/
│ ├── session.py # Playwright with persistent profile
│ ├── extractors.py # List/detail extraction and normalization
│ └── profile_lock.py # Cross-process profile lock
├── services/
│ ├── browser_service.py # Sync, query, comparison, review, and export
│ └── metrics.py # Derived metrics and sorting formulas
├── storage/
│ ├── db.py # SQLite, migration, and backup
│ └── schemas.sql # Data table structure
└── tools/
└── browser_tools.py # 13 MCP tool contracts
easy-install.ps1 # Windows one-click installation
```
### Extension Principles
1. Page reading and DOM processing are placed in `browser/`.
2. Testable business logic is placed in `services/`.
3. MCP tools only perform parameter declaration, service call, and unified error response.
4. Raw data, derived indicators, and different collection sources are saved separately.
5. New fields must define missing semantics, data sources, parsing versions, and test cases.
6. Do not read or return browser authentication materials, and do not access unpublished private interfaces.
### Basic Verification
```powershell
python -m compileall -q src
```
### Real Browser Acceptance
For changes involving DOM, indicator extraction, or browser lifecycle, run with a test account:
```powershell
douyin-mcp doctor
douyin-mcp login --timeout 180
douyin-mcp sync
douyin-mcp details --recent-limit 5
douyin-mcp status
```
During acceptance, verify login state reuse, page declaration count, loading count, parsing count, repeated synchronization idempotence, detail identity verification, coverage, and failure reasons. Real account data and acceptance results must not be submitted to the repository.
</details>
## Security, Compliance, and Licensing
`douyin-mcp` is an independently maintained third-party open-source project, not an official, authorized, certified, or cooperative product of Douyin, ByteDance, or its affiliated companies.
Douyin's User Service Agreement, Articles 2.4, 5.1, 5.3, and 7.1, involve non-commercial licenses, automated access, platform external processing or display information, providing information to third parties, and account disposal risks. Users must confirm they have legitimate accounts, data access rights, and all written authorizations required for automated access, platform external processing or display, and providing data to agents or model services. For a complete description, see [Platform Compliance and Non-Official Statement](PLATFORM_COMPLIANCE.md).
This project does not return cookies, `localStorage`, `sessionStorage`, verification codes, or account passwords through MCP, but work information and business data may enter the MCP client and agent context. "Local running" does not mean business data will not leave the local machine.
The project is open-sourced under the [GNU Affero General Public License v3.0](LICENSE) (`AGPL-3.0-only`). AGPL allows commercial use of the code, but modified versions distributed and network interaction scenarios require corresponding source code to be provided according to the license. The license does not grant access to the Douyin platform, data rights, commercial use of the platform or data, or trademark rights.
Copyright (C) 2026 Kuhakucai. `Kuhakucai` and `Puppetsho` are the same author using Git submission identities, see [AUTHORS.md](AUTHORS.md).
## Participate in Contributions
Feel free to submit issues and pull requests. Before starting, please read:
- [Contribution Guide](CONTRIBUTING.md)
- [Platform Compliance Statement](PLATFORM_COMPLIANCE.md)
- [Open-source License](LICENSE)
<div align="center">
<p><strong>If this project helps you, welcome to give it a star.</strong></p>
<p>Built for local, evidence-backed creator analytics.</p>
</div>
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available