Tiktok Business MCP

TikTok商业MCP服务器

一个全面的模型上下文协议（MCP）服务器，提供与TikTok业务API交互的工具。该服务器通过标准化的界面实现了对TikTok广告平台、业务中心、账户管理、创作者市场等的程序化访问。

  

🚀 特性

API全面覆盖

• 活动管理：创建、阅读、更新和管理广告活动
• 广告组管理：管理广告系列中的广告组
• 广告管理：创建和管理个人广告
• 创造性管理：上传和管理视频/图像创意
• 报告：生成全面的广告报告和分析
• 账户管理：管理商务中心广告商帐户
• 像素管理：创建和管理跟踪像素
• 内容发布：将内容发布到TikTok帐户
• 创造者发现：搜索并寻找合作创作者
• 产品管理：上传和管理产品目录
• 目标定位工具：获取支持的语言、地区和兴趣类别

增强的开发人员体验

• ✅ 标准化身份验证：一致的基于环境变量的身份验证
• ✅ 内置速率限制：自动处理TikTok API费率限制
• ✅ 输入验证：具有详细错误消息的全面参数验证
• ✅ 类型安全：具有严格类型的完整TypeScript实现
• ✅ 错误处理：具有特定错误代码和消息的强大错误处理
• ✅ 结构化日志记录：JSON结构化日志，用于更好的调试和监控
• ✅ 重试逻辑：瞬时故障和超出速率限制时自动重试

📋 先决条件

• Node.js 18.0或更高版本
• TikTok商业开发者账户
• 有效的TikTok Business API证书

🛠️ 安装

1.克隆存储库

git clone https://github.com/ebgolden/tiktok-business-mcp.git
cd tiktok-business-mcp

2.安装依赖项

npm install

3.建设项目

npm run build

🔑 API凭据设置

第一步：创建TikTok商业开发者账户

1. 访问 TikTok商业开发者门户
2. 创建一个帐户并注册您的应用程序
3. 完成申请审核流程

步骤2：获取API凭据

您需要以下凭据：

• 访问令牌：长期访问令牌（推荐）或OAuth令牌
• 广告商ID：TikTok广告管理器中的广告商帐户ID
• 应用程序ID （可选）：用于令牌刷新功能
• 应用程序密钥 （可选）：用于令牌刷新功能

步骤3：查找您的广告商ID

1. 登录到 TikTok广告经理
2. 广告商ID显示在URL或帐户设置中
3. 格式：通常是一个长数字字符串（例如。， 1234567890123456789)

⚙️ 配置

环境变量

创建一个 .env 项目根目录中的文件：

# Required
TIKTOK_ACCESS_TOKEN=your_long_term_access_token
TIKTOK_ADVERTISER_ID=your_advertiser_id

# Optional - for token refresh functionality
TIKTOK_APP_ID=your_app_id
TIKTOK_APP_SECRET=your_app_secret

# Optional - server configuration
TIKTOK_API_BASE_URL=https://business-api.tiktok.com
TIKTOK_RATE_LIMIT_RPM=200
DEBUG=true

MCP客户端配置

将此服务器添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "tiktok-business-api": {
      "command": "node",
      "args": ["path/to/tiktok-business-mcp/dist/index.js"],
      "env": {
        "TIKTOK_ACCESS_TOKEN": "your_long_term_access_token",
        "TIKTOK_ADVERTISER_ID": "your_advertiser_id",
        "TIKTOK_APP_ID": "your_app_id",
        "TIKTOK_APP_SECRET": "your_app_secret",
        "DEBUG": "true"
      }
    }
  }
}

📖 使用示例

活动管理

创建新活动

{
  "tool": "tiktok_campaign_create",
  "arguments": {
    "campaign_name": "Holiday Sales Campaign 2024",
    "objective_type": "CONVERSIONS",
    "budget": 1000.00,
    "budget_mode": "BUDGET_MODE_TOTAL",
    "schedule_type": "SCHEDULE_START_END",
    "schedule_start_time": "2024-12-01 00:00:00",
    "schedule_end_time": "2024-12-31 23:59:59"
  }
}

使用筛选检索活动

{
  "tool": "tiktok_campaign_get",
  "arguments": {
    "page": 1,
    "page_size": 20,
    "filtering": {
      "primary_status": "ENABLE",
      "objective_type": "CONVERSIONS"
    }
  }
}

创造性管理

上传视频创意

{
  "tool": "tiktok_video_upload",
  "arguments": {
    "video_file": "https://example.com/product-demo.mp4",
    "upload_type": "UPLOAD_BY_URL",
    "video_name": "Holiday Product Demo Video",
    "flaw_detect": true,
    "auto_bind_enabled": true,
    "auto_fix_enabled": true
  }
}

报告和分析

生成绩效报告

{
  "tool": "tiktok_report_get",
  "arguments": {
    "report_type": "BASIC",
    "data_level": "AUCTION_CAMPAIGN", 
    "dimensions": ["stat_time_day", "campaign_id"],
    "metrics": ["spend", "impressions", "clicks", "ctr", "cpm", "conversions"],
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "filters": [
      {
        "field_name": "campaign_name",
        "filter_type": "IN",
        "filter_value": ["Holiday Sales Campaign 2024"]
      }
    ],
    "page": 1,
    "page_size": 100
  }
}

🛠️ 可用工具

活动目标

• REACH：最大限度地扩大覆盖面和品牌知名度
• TRAFFIC：为网站或应用程序带来流量
• APP_INSTALL：增加移动应用安装
• VIDEO_VIEW：最大化视频观看量和参与度
• LEAD_GENERATION：生成潜在客户和联系人
• CONVERSIONS：驱动特定的转换操作
• CATALOG_SALES：推广目录中的产品

可用指标

绩效指标：

• spend, impressions, clicks, ctr, cpm, cpc

转化指标：

• conversions, conversion_rate, cost_per_conversion

参与度指标：

• video_play_actions, video_watched_2s, video_watched_6s
• likes, comments, shares, follows

报告维度

• stat_time_day：每日明细
• campaign_id：活动级别数据
• adgroup_id：广告组级数据
• ad_id：广告级别数据
• age：观众年龄细分
• gender：观众性别细分

🔐 安全最佳实践

许可证管理

• 尽可能使用长期访问令牌进行生产
• 使用环境变量或秘密管理系统安全地存储令牌
• 切勿在客户端代码或版本控制中公开令牌
• 如果使用应用程序凭据，则实现令牌轮换
• 监控令牌过期并自动刷新

网络安全

• 所有API调用都使用HTTPS加密
• 如果您的基础架构需要，实施IP白名单
• 使用安全的网络连接进行生产部署

错误处理

• 敏感信息从不记录在错误消息中
• API错误在返回客户端之前被清除
• 利率限制可防止滥用

📊 速率限制

TikTok商业API有以下速率限制：

服务器通过以下方式自动处理速率限制：

• 内置速率限制器，可配置限制
• 指数回退自动重试
• 突发请求的队列管理

🐛 故障排除

常见问题

身份验证错误

错误: Authentication failed. Please check your access token.

解决方案:

• 验证 TIKTOK_ACCESS_TOKEN 设置正确
• TikTok广告管理器中的支票令牌尚未过期
• 确保令牌具有操作所需的权限
• 验证 TIKTOK_ADVERTISER_ID 匹配您的帐户

# Test your credentials
curl -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
     "https://business-api.tiktok.com/open_api/v1.3/advertiser/info/?advertiser_id=$TIKTOK_ADVERTISER_ID"

环境变量问题

错误: TIKTOK_ACCESS_TOKEN environment variable is required

解决方案:

• 检查环境变量名称是否准确（区分大小写）
• 验证值中没有多余的空格或引号
• 确保 .env 文件位置正确
• 检查MCP客户端配置是否包括所有必需的变量

利率限制问题

错误: Rate limit exceeded

解决方案:

• 服务器在速率限制后自动重试
• 如果遇到持续限制，请降低请求频率
• 考虑升级您的TikTok API访问级别
• 尽可能实施请求批处理

API参数验证错误

错误: Invalid parameters: campaign_name: String must contain at least 1 character(s)

解决方案:

• 检查是否提供了所有必需的参数
• 验证参数格式是否与文档匹配
• 在IDE中使用JSON模式验证
• 查看工具描述中的参数约束

调试模式

启用详细日志记录：

DEBUG=true node dist/index.js

这将输出详细的请求/响应日志和时间信息。

健康检查

测试服务器连接：

# Check if server starts properly
node dist/index.js --health-check

# Test with minimal configuration
TIKTOK_ACCESS_TOKEN=test TIKTOK_ADVERTISER_ID=test node dist/index.js

🔧 发展

发展的先决条件

npm install -g typescript nodemon

开发设置

# Install dependencies
npm install

# Start development server with hot reload
npm run dev

# Run linting
npm run lint

# Format code
npm run format

项目结构

tiktok-business-mcp/
├── src/
│   ├── index.ts              # Main server implementation
├── dist/                     # Compiled output
├── package.json
├── tsconfig.json
└── README.md

添加新工具

1. 在客户端类中添加API方法
2. 在主服务器中注册该工具
3. 为新功能添加测试
4. 更新文档

📈 性能优化

最佳实践

• 批量操作：在可用时使用批处理端点
• 缓存：对频繁访问的数据实施缓存
• 分页：使用适当的页面大小（20-100个项目）
• 过滤：应用过滤器以减少数据传输
• 压缩：为大型响应启用gzip压缩

监控

监控这些指标：

• 请求延迟和错误率
• 速率限制利用率
• 令牌过期警告
• API配额使用情况

🤝 贡献

我们欢迎捐款！

开发过程

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 添加新功能的测试
5. 确保所有测试通过(npm test)
6. 抓取你的代码(npm run lint)
7. 提交您的更改(git commit -m 'Add amazing feature')
8. 推到您的分支(git push origin feature/amazing-feature)
9. 打开拉取请求

代码规范

• 遵循TypeScript的最佳实践
• 使用有意义的变量和函数名
• 为公共API添加JSDoc注释
• 遵循语义版本控制发布

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🆘 支持

针对TikTok API问题

• 访问 TikTok API商业开发者门户
• 点击右上角的“？”提交API营销类别下的票证

关于MCP问题

• 访问 模型上下文协议文档
• 检查 获取更新

对于本项目

• 在GitHub上打开一个问题
• 检查现有问题是否存在类似问题
• 提供详细的错误消息和环境信息

📚 额外资源

• TikTok业务API文档
• 模型上下文协议规范
• TypeScript文档

由以下材料制成❤️ TikTok开发者社区