Tiktok Ads MCP Server

🚀 TikTok Ads MCP Server

A Model Context Protocol (MCP) server for integrating with the TikTok Ads API. This server allows AI assistants like Claude to interact with TikTok advertising campaigns, offering comprehensive campaign management, analytics, and optimization capabilities.

This project is part of AdsMCP, which provides MCP servers for advertising platforms.

🚀 Quick Start

The TikTok Ads MCP Server enables seamless integration with the TikTok Ads API, allowing AI assistants to manage advertising campaigns. To get started, follow the installation and configuration steps below.

✨ Features

• Campaign Management: Create, read, and update campaigns and ad groups.
• Performance Analytics: Retrieve detailed performance metrics and insights.
• Audience Management: Handle custom audiences and targeting options.
• Creative Management: Upload and manage ad creatives.
• Reporting: Generate and download custom performance reports.

📦 Installation

Prerequisites

• Python 3.10+
• A TikTok For Business account with API access.
• A TikTok Ads Developer account and app registration.

Local Installation

# Clone the repository
git clone <repository-url>
cd adsmcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

Using uv (recommended)

# Install with uv
uv sync

📚 Documentation

Configuration

MCP Client Configuration

Add the following to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "tiktok-ads": {
      "command": "python",
      "args": ["/path/to/adsmcp-server/run_server.py"],
      "cwd": "/path/to/adsmcp-server",
      "env": {
        "TIKTOK_APP_ID": "your_app_id",
        "TIKTOK_APP_SECRET": "your_app_secret"
      }
    }
  }
}

Available Tools

Authentication

• tiktok_ads_login - Initiate the TikTok Ads OAuth authentication flow.
• tiktok_ads_complete_auth - Complete the OAuth authentication using the authorization code.
• tiktok_ads_auth_status - Check the current authentication status.
• tiktok_ads_switch_ad_account - Switch to a different advertiser account.

Campaign Management

• tiktok_ads_get_campaigns - Retrieve all campaigns for the advertiser account.
• tiktok_ads_get_campaign_details - Get detailed information about a specific campaign.
• tiktok_ads_get_adgroups - Retrieve ad groups for a campaign.

Performance & Analytics

• tiktok_ads_get_campaign_performance - Get performance metrics for campaigns with detailed metrics support.
• tiktok_ads_get_adgroup_performance - Get performance metrics for ad groups with breakdowns.

Authentication

TikTok Ads API Setup

1. Register as Developer
   • Visit the TikTok For Business Developer Portal.
   • Create a developer account.
   • Register your application.
2. Get API Credentials
   • Obtain the App ID and App Secret from your registered app.
   • Generate an access token through the OAuth flow.
   • Note down your Advertiser ID.
3. OAuth Flow (for production)
   • Implement the OAuth 2.0 flow for user authorization.
   • Automatically handle token refresh.
   • Store tokens securely.

Security Best Practices

• Never commit API credentials to version control.
• Use environment variables for sensitive data.
• Implement proper token rotation.
• Monitor API usage and rate limits.
• Use HTTPS for all communications.

API Rate Limits

The TikTok Ads API has the following limits:

• 1000 requests per hour per app.
• 10 concurrent requests.
• Specific endpoint limits may apply.

The server includes built - in rate limiting and retry logic.

Error Handling

The server provides comprehensive error handling, including:

• API rate limit management.
• Token expiration handling.
• Network connectivity issues.
• Invalid parameter validation.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

💬 Support

For issues and questions, please create an issue in this repository.

📝 Changelog

v0.1.0 (Initial Release)

• Basic TikTok Ads API integration.
• Campaign and ad group management.
• Performance reporting.
• OAuth authentication support.