TikTok Ads MCP

A read-only Model Context Protocol (MCP) server for retrieving TikTok advertising accounts, campaigns, ad groups, ads, and performance reports.

Features

• Read-Only TikTok Business API Integration: Access all major TikTok advertising endpoints for data retrieval
• 6 Read-Only Tools: Business centers, ad accounts, campaigns, ad groups, ads, and reports
• API-aligned Filtering: Filtering and pagination for campaigns, ad groups, ads, and reports
• Multi-Advertiser Support: Handle multiple advertiser accounts in a single request
• Flexible Reporting: Generate detailed performance reports with custom dimensions and metrics
• Current Data: Retrieve current advertising data and performance metrics
• Error Handling: Comprehensive error handling and validation
• Modular Architecture: Clean, maintainable code structure
• Safe Operations: All tools are read-only and will not modify your campaigns or ad data

Available Tools

1. get_business_centers - Retrieve business centers accessible by your access token
2. get_authorized_ad_accounts - Get all authorized advertiser accounts
3. get_campaigns - Retrieve campaigns with filtering and pagination
4. get_ad_groups - Retrieve ad groups with filtering and pagination
5. get_ads - Retrieve ads with filtering and pagination
6. get_reports - Generate performance reports and analytics

Prerequisites

• Python 3.10 or higher
• TikTok Business API access
• Valid API credentials (app ID, secret, access token)

Quick Start

Installation

1. Download the TikTok Ads MCP

   • Click the green "Code" button at the top of the GitHub page
   • Select "Download ZIP"
   • Unzip the downloaded file to a location you can easily find (like your Documents folder)

2. Alternatively, if you're familiar with Git:

   git clone https://github.com/ysntony/tiktok-ads-mcp.git
   

3. Install Dependencies

   cd tiktok-ads-mcp
   pip install -e .
   # or with uv
   uv pip install -e .
   

Configuration

1. Set up environment variables in your MCP client configuration:

{
  "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"
      }
    }
  }
}

1. Required credentials:

   • TIKTOK_APP_ID: Your TikTok app ID
   • TIKTOK_SECRET: Your TikTok app secret
   • TIKTOK_ACCESS_TOKEN: Your access token

   How to get these credentials:

   1. Go to the TikTok for Business Developers portal and log in.
   2. Click "My Apps" and create a new app.
   3. Select "Marketing API" as the service type.
   4. In the app settings, enable permissions related to Reading and Reporting (e.g., Ads Management, Reporting).
   5. Once approved, you will find your App ID and Secret in the app details.
   6. Generate an Access Token using the "TikTok Marketing API Inspector" or via the OAuth flow documented in the portal.

Usage

Once configured, you can use the MCP tools through your MCP client (like Cursor, Claude Desktop, etc.):

• Get business centers and advertiser accounts to discover available accounts
• Retrieve campaigns with filtering by status, objective, or date range
• Access ad groups with advanced targeting and optimization settings
• View ads with detailed creative and performance data
• Generate reports with custom dimensions, metrics, and time ranges
• Access current advertising data and performance metrics

API Coverage

This MCP server provides read-only access to the TikTok Business API:

Business Management

• Business center retrieval and access
• Advertiser account information and permissions

Campaign Management

• Campaign retrieval and filtering
• Campaign status and performance monitoring
• Campaign budget and objective information

Ad Group Management

• Ad group retrieval and filtering
• Advanced targeting and optimization settings
• Performance monitoring and analysis

Ad Management

• Ad retrieval and filtering
• Creative asset information
• Performance tracking and analysis

Reporting & Analytics

• Basic performance reports
• Audience insights reports
• Playable ads reports
• DSA (Dynamic Search Ads) reports
• Business Center reports
• Legacy GMV Max reports (TT_SHOP) are not supported because TikTok is deprecating that report type; use the dedicated GMV Max report endpoint when adding GMV Max support.

Key Features

Filtering and pagination

Supported data tools expose API-aligned filters and pagination:

• Status-based filtering (active, paused, deleted)
• Time-based filtering (creation date, modification date)
• Campaign, ad group, and ad identifiers
• Objective, optimization, placement, and creative filters where supported by TikTok
• Page number and page size, with page_info returned for paginated endpoints

Modern Implementation

This package uses the FastMCP framework for optimal performance and developer experience:

• Automatic Schema Generation: From Python type hints
• Simplified Tool Registration: Using @app.tool() decorators
• Built-in Error Handling: Consistent error responses
• Type Safety: Full parameter validation from type hints

Multi-Advertiser Support

• Handle multiple advertiser accounts in single requests
• Cross-advertiser reporting and analytics
• Unified data access across accounts

Flexible Reporting

• Custom dimensions and metrics
• Multiple report types and data levels
• Time-based and lifetime metrics
• Aggregated and detailed views

Error Handling

• Comprehensive parameter validation
• Detailed error messages and suggestions
• Graceful handling of API limitations
• Rate limiting and retry logic

Documentation

• MCP_USAGE.md: Comprehensive usage guide with examples
• TikTok Business API: Official API documentation
• Project Wiki: Additional resources and guides

Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests and documentation
5. Submit a pull request

License

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

Support

For issues and questions:

1. Check the MCP_USAGE.md documentation
2. Review the TikTok Business API documentation
3. Open an issue on the GitHub repository
4. Contact the development team

Changelog

v0.1.5 (Current)

• Protocol safety: Startup and error messages no longer pollute MCP stdio output.
• Security: Access tokens and OAuth secrets are redacted from debug logs.
• Campaign queries: Campaign filters now use TikTok v1.3's filtering object and support pagination.
• Response compatibility: List tools preserve newly added TikTok fields and return pagination metadata.
• Reporting validation: Unsupported report combinations are rejected early; deprecated TT_SHOP reports are blocked.
• Configuration: .env files are loaded automatically.
• Example startup: Fixed the example entry point to call the synchronous server correctly.

v0.1.4

• Retry Logic Fix: Fixed retry decorator being defeated by inner exception handling — retries now actually fire on rate limits and transient errors
• Pagination Fix: page and page_size params now properly passed through to get_ad_groups and get_ads API calls
• Security: Access token redacted from debug log output
• Dependencies: Removed unused requests and pandas, bumped mcp to >=1.27.0, added httpx and tenacity to requirements.txt
• Code Quality: Modernized type annotations to Python 3.10+ style, removed dead code and redundant error checks, fixed mutable default dict mutation in filter handling
• Python Compatibility: Lowered minimum Python version to 3.10

v0.1.3

• Async Support: Complete refactor to use async/await with httpx for improved performance
• Retry Logic: Added automatic retries for rate limits and server errors using tenacity
• Error Handling: Simplified and standardized error handling with decorators
• Dependencies: Switched from requests to httpx

v0.1.2

• FastMCP Implementation: Modern MCP server using official FastMCP framework
• 70% Code Reduction: Compared to traditional MCP implementations
• Automatic Schema Generation: From Python type hints
• Simplified Tool Registration: Using @app.tool() decorators
• Enhanced Error Handling: Built-in error handling with consistent responses
• Type Safety: Full parameter validation from type hints
• Future-Proof: Part of the official MCP SDK

v0.1.1

• Complete implementation of all 6 tools
• Advanced filtering and reporting capabilities
• Multi-advertiser support
• Comprehensive error handling
• Modular tools architecture
• Complete documentation and usage guides

v0.1.0

• Initial release with basic MCP server structure
• Core API client implementation
• Basic authentication and configuration