TikTok广告MCP
用于与TikTok Business API交互的综合模型上下文协议（MCP）服务器。该软件包提供了一个完整的界面，用于访问TikTok广告活动、广告组、广告，并生成详细的绩效报告。
特性
- Read-Only TikTok Business API集成：访问所有主要的TikTok广告端点进行数据检索
- 6综合工具：业务中心、广告账户、活动、广告组、广告和报告
- 高级过滤：为所有数据检索操作提供强大的过滤选项
- 多广告主支持：在单个请求中处理多个广告商帐户
- 灵活的报告：生成具有自定义维度和指标的详细绩效报告
- 实时数据：访问实时广告数据和绩效指标
- 错误处理：全面的错误处理和验证
- 模块化架构：干净、可维护的代码结构
- 安全操作：所有工具都是只读的，不会修改您的广告系列或广告数据
可用工具
- get_business_center -检索您的访问令牌可访问的业务中心
- 获取授权数 -获取所有授权广告商帐户
- get_campaigns -使用全面的筛选选项检索活动
- 获取_组 -使用高级过滤和定位选项获取广告组
- get_ads -检索具有详细创意和性能数据的广告
- 获取报告 -生成全面的绩效报告和分析
先决条件
- Python 3.14.0或更高版本
- TikTok Business API访问
- 有效的API凭据（应用程序ID、机密、访问令牌）
快速开始
安装
- 下载TikTok广告MCP
- 点击GitHub页面顶部的绿色“代码”按钮 - 选择“下载ZIP” - 将下载的文件解压缩到您可以轻松找到的位置（如您的Documents文件夹）
- 或者，如果你熟悉Git：
git clone https://github.com/ysntony/tiktok-ads-mcp.git- 再进行
cd tiktok-ads-mcp
pip install -e .配置
- 设置环境变量 在MCP客户端配置中：
{
"mcpServers": {
"tiktok-ads": {
"command": "python",
"args": ["-m", "tiktok_ads_mcp"],
"env": {
"TIKTOK_APP_ID": "your_app_id",
"TIKTOK_SECRET": "your_secret",
"TIKTOK_ACCESS_TOKEN": "your_access_token"
}
}
}
}- 所需凭据:
- TIKTOK_APP_ID：让我们试试这个。应用程序ID - TIKTOK_SECRET：你的TikTok应用程序秘密 - TIKTOK_ACCESS_TOKEN：您的访问令牌
如何获取这些凭据：
1. 去 面向商业开发人员的TikTok 门户并登录。 1. 单击“我的应用程序”并创建新应用程序。 1. 选择“营销API”作为服务类型。 1. 在应用程序设置中，启用与以下内容相关的权限 阅读 和 报告 （例如。， Ads Management, Reporting). 1. 一旦获得批准，您将发现您的 App ID 和 Secret 在应用程序详细信息中。 1. 生成一个 Access Token 使用“TikTok营销API检查器”或通过门户网站中记录的OAuth流程。
用法
配置后，您可以通过MCP客户端使用MCP工具（如Cursor、Claude Desktop等）：
- 获取业务中心和广告商帐户 查找可用帐户
- 检索活动 按状态、目标或日期范围进行筛选
- 访问广告组 具有高级定位和优化设置
- 查看广告 有详细的创意和表演数据
- 生成报告 具有自定义维度、度量和时间范围
- 访问实时广告数据 以及性能指标
API覆盖范围
此MCP服务器提供 只读 访问TikTok Business API：
商业管理
- 商务中心检索和访问
- 广告商帐户信息和权限
活动管理
- 活动检索和过滤
- 活动状态和性能监控
- 活动预算和目标信息
广告组管理
- 广告组检索和过滤
- 高级定位和优化设置
- 性能监测和分析
广告管理
- 广告检索和过滤
- 创意资产信息
- 性能跟踪和分析
报告和分析
- 基本绩效报告
- 受众洞察报告
- 可播放广告报告
- DSA（动态搜索广告）报告
- 商务中心报告
- GMV最大广告报告
主要特点
高级过滤
所有工具都支持全面的过滤选项：
- 基于状态的筛选（活动、暂停、删除）
- 基于时间的过滤（创建日期、修改日期）
- 基于性能的过滤（预算、优化目标）
- 创意过滤（广告格式、素材类型）
现代实施
此软件包使用官方的FastMCP框架，以获得最佳性能和开发人员体验：
- 自动模式生成：来自Python类型提示
- 简化工具注册：使用
@app.tool()装饰器 - 内置错误处理：一致的错误响应
- 类型安全：根据类型提示进行完整的参数验证
- 面向未来：官方MCP SDK的一部分
多广告主支持
- 在单个请求中处理多个广告商帐户
- 跨广告商报告和分析
- 跨帐户的统一数据访问
灵活的报告
- 自定义尺寸和度量
- 多种报告类型和数据级别
- 基于时间和生命周期的度量
- 汇总视图和详细视图
错误处理
- 全面的参数验证
- 详细的错误消息和建议
- 优雅地处理API限制
- 速率限制和重试逻辑
文档
- MCP_USAGE.md：带示例的综合使用指南
- TikTok业务API：API官方文件
- 维基工程：额外资源和指南
贡献
- 分叉存储库
- 创建要素分支
- 实施您的更改
- 添加测试和文档
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
支持
对于问题和疑问：
- 检查 MCP_USAGE.md 文档
- 查看 TikTok业务API文档
- 在GitHub存储库上打开一个问题
- 联系开发团队
更新日志
v0.1.3（当前）
- 异步支持：完全重构以使用
async/await随着httpx为了提高性能 - 重试逻辑：使用添加了针对速率限制和服务器错误的自动重试
tenacity - 错误处理：使用装饰器简化和标准化错误处理
- 依赖项：已切换
requests到httpx
v0.1.2
- FastMCP实施：使用官方FastMCP框架的现代MCP服务器
- 代码减少70%：与传统的MCP实施相比
- 自动模式生成：来自Python类型提示
- 简化工具注册：使用
@app.tool()装饰器 - 增强的错误处理：具有一致响应的内置错误处理
- 类型安全：根据类型提示进行完整的参数验证
- 面向未来：官方MCP SDK的一部分
v0.1.1
- 完成所有6个工具的实施
- 高级过滤和报告功能
- 多广告商支持
- 全面的错误处理
- 模块化工具架构
- 完整的文档和使用指南
v0.1.0
- 具有基本MCP服务器结构的初始版本
- 核心API客户端实现
- 基本身份验证和配置