内容
# TikTok 爬虫 MCP
用于通过廉价的 HTTP-first 获取器、确定性的固定测试和可选的浏览器回退来抓取公共 TikTok 元数据的本地 Go MCP 服务器。
> GitHub 描述: 用于公共 TikTok 元数据抓取的本地 Go MCP 服务器，具有 HTTP-first 提取、固定测试合约和可选的浏览器回退。
## 状态
该项目是用于本地 MCP 使用的 MVP。它不是托管的抓取服务，不需要 Docker，也不使用 TikTok 登录 cookie。
当前实时行为:
- 直接视频 URL 元数据通过 `public_http` 使用有界重试。
- 公共资料元数据通过 `public_http` 工作，当 TikTok 返回水化有效载荷时。
- 浏览器模式作为回退可用，但对于直接视频来说，它较慢，不应作为默认。
- 配置文件视频列表尚未声称已解决。TikTok 通过签名的 `api/post/item_list` 请求公开它们，因此当前合约在列表不可用时返回结构化的 `TARGET_DRIFT`。
TikTok 经常更改其网页有效载荷。固定测试是确定性合约；实时烟雾测试是可选的。
## 功能
- MCP `stdio` 服务器。
- 由 `github.com/skosovsky/toolsy` 驱动的键入工具。
- 仅公共数据，无 TikTok 登录。
- 仅元数据输出，无媒体下载。
- 直接视频 URL 抓取。
- 公共资料元数据抓取。
- 结构化错误项而不是静默部分失败。
- 用于大型 MCP 响应的内存游标缓存。
- 具有三种模式的获取器接口：
- `public_http`
- `browser`
- `fixture`
- 原始固定提取和确定性测试。
## 要求
- Go `1.26.3` 或更新版本，与模块兼容。
- `jq` 用于 JSON 固定验证。
- 如果使用 `TIKTOK_MCP_FETCHER_MODE=browser`，则需要 Google Chrome。
## 安装
安装 MCP 服务器二进制文件：
```bash
go install github.com/skosovsky/tiktok-scraper/cmd/tiktok-scraper-mcp@latest
```
确保 Go 二进制目录在 `PATH` 上：
```bash
export PATH="$(go env GOPATH)/bin:$PATH"
```
对于本地开发，从项目根目录克隆存储库并运行验证命令。
## MCP 客户端配置
使用二进制文件的绝对路径。示例：
```json
{
"mcpServers": {
"tiktok-scraper": {
"command": "/absolute/path/to/tiktok-scraper-mcp",
"env": {
"TIKTOK_MCP_LOG_LEVEL": "info",
"TIKTOK_MCP_FETCHER_MODE": "public_http",
"TIKTOK_MCP_MAX_RETRIES": "3"
}
}
}
}
```
服务器通过 `stdio` 使用 MCP。日志写入 `stderr`；`stdout` 保留用于 MCP 帧。
## 工具
### `tiktok_scrape`
抓取支持的 TikTok 输入。
示例参数：
```json
{
"videoUrls": [
"https://www.tiktok.com/@tiktok/video/7651659857640033566"
]
}
```
资料示例：
```json
{
"profiles": ["tiktok"],
"limit": 5
}
```
### `tiktok_get_more`
从内存游标缓存中读取下一页，当 `tiktok_scrape` 返回 `hasMore=true` 时。
### `tiktok_validate_input`
验证输入而不抓取。
## 手动 MCP 烟雾测试
列出工具：
```bash
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./tiktok-scraper-mcp
```
调用 `tiktok_scrape`：
```bash
printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"tiktok_scrape","arguments":{"videoUrls":["https://www.tiktok.com/@tiktok/video/7651659857640033566"]}}}' | ./tiktok-scraper-mcp
```
## 获取器模式
| 模式 | 环境值 | 目的 | 备注 |
| --- | --- | --- | --- |
| 公共 HTTP | `public_http` | 直接视频和资料元数据的默认实时模式 | 最便宜的模式。使用 Go HTTP、公共 HTML 有效载荷、提取回退和有界重试。 |
| 浏览器 | `browser` | 回退和发现模式 | 通过 `chromedp` 使用本地无头 Chrome。较慢且更昂贵。需要 Google Chrome。 |
| 固定 | `fixture` | 确定性测试和本地合约检查 | 从 `fixtures/` 读取，无需网络。 |
默认：
```bash
TIKTOK_MCP_FETCHER_MODE=public_http
```
浏览器回退：
```bash
TIKTOK_MCP_FETCHER_MODE=browser
TIKTOK_MCP_HTTP_TIMEOUT=45s
TIKTOK_MCP_FETCH_CONCURRENCY=1
TIKTOK_MCP_PER_HOST_CONCURRENCY=1
```
固定模式：
```bash
TIKTOK_MCP_FETCHER_MODE=fixture
```
## 配置
服务器通过环境变量配置。
重要设置：
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `TIKTOK_MCP_FETCHER_MODE` | `public_http` | `public_http`、`browser` 或 `fixture`。 |
| `TIKTOK_MCP_HTTP_TIMEOUT` | `30s` | 获取超时。 |
| `TIKTOK_MCP_MAX_RETRIES` | `3` | 暂时性获取错误、重试分类和目标漂移的有界重试次数。 |
| `TIKTOK_MCP_DEFAULT_LIMIT` | `20` | 默认项目限制。 |
| `TIKTOK_MCP_MAX_LIMIT` | `100` | 硬限制。 |
| `TIKTOK_MCP_RESPONSE_ITEM_LIMIT` | `50` | 游标分页前的内联响应项目限制。 |
| `TIKTOK_MCP_CURSOR_TTL` | `30m` | 内存游标 TTL。 |
| `TIKTOK_MCP_USER_AGENT` | 类似 Chrome 的 UA | 实时获取器的用户代理。 |
| `TIKTOK_MCP_ACCEPT_LANGUAGE` | `en-US,en;q=0.9` | 接受语言头。 |
示例：
- `.env.example`
- `.env.live.example`
- `../docs/tiktok-scraper/configuration.md`
## 测试
确定性本地检查：
```bash
go test -count=1 ./...
jq empty fixtures/expected/*.json fixtures/json/*.json fixtures/meta/*.json
go build ./cmd/tiktok-scraper-mcp
```
快速实时直接视频烟雾测试：
```bash
go test -count=20 -tags=public_network ./internal/scraper -run TestPublicNetworkHTTPVideoScrapeSmoke -v
```
资料元数据烟雾测试：
```bash
go test -count=10 -tags=public_network ./internal/scraper -run TestPublicNetworkProfileScrapeSmoke -v
```
浏览器回退烟雾测试：
```bash
go test -count=1 -tags=public_network ./internal/scraper -run 'TestPublicNetwork(BrowserVideoScrapeSmoke|BrowserProfileScrapeSmoke)' -v
```
实时测试是可选的，可能会随着 TikTok 更改其公共网络界面而发生变化。
## 文档
深入文档位于工作区级文档文件夹中：
- `../docs/tiktok-scraper/README.md`
- `../docs/tiktok-scraper/problem-solving-log.md`
- `../docs/tiktok-scraper/scraping-strategy.md`
- `../docs/tiktok-scraper/discovery-notes.md`
- `../docs/tiktok-scraper/testing-strategy.md`
- `../docs/scraping.md`
## 边界
该项目故意不提供：
- TikTok 登录支持。
- CAPTCHA 解答。
- 代理/会话池管理。
- 媒体下载。
- 远程 MCP 传输。
- Docker 包装。
- 持久存储。
- 保证的资料视频分页。
## 许可证
MIT。参见 `LICENSE`。
