Tiktok Ads Mcp Server

by AdsMCP

460 downloads
Not rated
GitHub

Description

A Model Context Protocol (MCP) server for TikTok Ads API integration. This server enables AI assistants like Claude to interact with TikTok advertising campaigns, providing comprehensive campaign management, analytics, and optimization capabilities. Part of the AdsMCP project -…

About

A Model Context Protocol (MCP) server for TikTok Ads API integration. This server enables AI assistants like Claude to interact with TikTok advertising campaigns, providing comprehensive campaign management, analytics, and optimization capabilities. Part of the AdsMCP project - MCP servers for advertising platforms.

Details

Author
AdsMCP
Downloads
460
Categories
Productivity, Other, Marketing, API

Jump to

- Campaign management (create, read, update campaigns and ad groups)
- Performance analytics with detailed metrics and insights
- Audience management and custom targeting options
- Creative management (upload and manage ad creatives)
- Reporting and custom performance report generation

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Tiktok Ads Mcp Server
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Install Python 3.10+, clone the repository, set up a virtual environment, and install dependencies via pip install -e . or uv sync. Configure environment variables (TIKTOK_APP_ID, TIKTOK_APP_SECRET, TIKTOK_ACCESS_TOKEN, TIKTOK_ADVERTISER_ID) and add the server to your MCP client’s configuration (e.g., Claude Desktop) with the command and environment variables.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "tiktok ads mcp server": {
            "tiktok-ads-mcp-server": {
                "command": "python",
                "args": [
                    "-m",
                    "venv",
                    "venv"
                ]
            }
        }
    }
}

McpServers

{
    "tiktok-ads-mcp-server": {
        "command": "python",
        "args": [
            "-m",
            "venv",
            "venv"
        ]
    }
}

A local Model Context Protocol (MCP) server for TikTok Ads API integration. It lets MCP clients such as Claude Desktop connect to TikTok Ads, authenticate with a TikTok Business app, and use read-only tools for campaign lookup, ad group and ad inspection, performance reporting, audience breakdowns, advertiser info, pixels, and targeting locations.

- Authentication: Start and complete TikTok Ads OAuth from an MCP client.
- Campaign lookup: List campaigns, inspect campaign details, list ad groups, and inspect ads.
- Performance analytics: Pull campaign, ad group, ad, and audience metrics for common date ranges.
- Audience and account data: Retrieve custom audiences, advertiser info, location IDs, pixels, and pixel event stats.
- Read-only operation: The public MCP tool registry does not expose campaign creation, ad group creation, creative upload, or other write operations.

This repository is for users who want to run a local TikTok Ads MCP server.

If you do not want to install Python, manage dependencies, or configure a TikTok developer app,AdsMCPprovides a hosted remote MCP server:

The rest of this README covers the local setup.

- Python 3.10 or newer
- uvfor dependency management
- A TikTok For Business account with Marketing API access
- A TikTok developer app with an App ID and App Secret
- An MCP client that supports local stdio servers, such as Claude Desktop

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, confirm thatuvis available:

Find the absolute path touvbefore configuring a desktop MCP client:

Use the path returned bywhereis uvorwhich uvas the MCPcommandvalue if your client cannot finduvby name.

- macOS/Linux:/Users/<your-name>/.local/bin/uv
- Windows:C:\\Users\\<your-name>\\.local\\bin\\uv.exe

Clone the repository and install dependencies:

git clone https://github.com/AdsMCP/tiktok-ads-mcp-server.git cd tiktok-ads-mcp-server uv sync

Find the absolute path to the project directory. You will use this path in the MCP config as theuv --directoryvalue:

Verify that the project environment can import MCP:

uv run python -c "from mcp.server import Server; print('ok')"

Do not configure your MCP client to run this server with systempythonorpython3unless you have manually installed all dependencies into that exact Python environment.

python run_server.py python3 run_server.py

Why: MCP desktop apps often launch a different Python than the one you use in your terminal. If that Python does not have themcppackage installed, the server exits with:

uv runmakes the MCP client use this project's dependency environment.

Claude Desktop reads its MCP server config from:

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\\Claude\\claude_desktop_config.json

Linux paths vary by distribution and client package, but they are usually under:

Useuv --directoryso the server starts from the project directory even if your MCP client does not applycwdcorrectly.

To fill in"/absolute/path/to/tiktok-ads-mcp-server", open a terminal in the cloned repository and run:

Use the printed value as the--directoryargument. If Claude cannot finduv, replace"uv"with the absolute path fromwhereis uvorwhich uv, such as"/Users/yourname/.local/bin/uv".

{ "mcpServers": { "tiktok-ads": { "command": "uv", "args": [ "--directory", "/absolute/path/to/tiktok-ads-mcp-server", "run", "python", "run_server.py" ], "env": { "TIKTOK_APP_ID": "your_app_id", "TIKTOK_APP_SECRET": "your_app_secret" } } } }

Use escaped backslashes in JSON paths. To find the project path, open PowerShell in the cloned repository and run:

Use the printed value as the--directoryargument, with each\escaped as\\in JSON:

{ "mcpServers": { "tiktok-ads": { "command": "uv", "args": [ "--directory", "C:\\path\\to\\tiktok-ads-mcp-server", "run", "python", "run_server.py" ], "env": { "TIKTOK_APP_ID": "your_app_id", "TIKTOK_APP_SECRET": "your_app_secret" } } } }

If Claude cannot finduvon Windows, use the full path:

"command": "C:\\Users\\yourname\\.local\\bin\\uv.exe"

After editing the config, fully restart Claude Desktop.
- Go to theTikTok For Business Developer Portal.
- Create or open a developer app.
- Copy the App ID and App Secret.
- Make sure the redirect URI configured in your TikTok app matches the redirect URI used by this server. By default, this project uses:
- Add the App ID and App Secret to your MCP client config underenv.
- Runtiktok_ads_loginfrom your MCP client.
- Open the authorization URL returned by the tool.
- Approve access in TikTok.
- Copy thecodeparameter from the redirect URL.
- Runtiktok_ads_complete_authwith that code.
- Runtiktok_ads_auth_statusto confirm the account is authenticated.

After OAuth completes, TikTok access and refresh tokens are stored locally under:

This file is what lets the local MCP server call TikTok Marketing API after you authenticate. Treat it like a password:

- Do not commit it to Git or share it in issue reports.
- Keep it on your own machine and protect it with your normal OS account permissions.
- Remove it if you want to disconnect the local server from your TikTok account.

The local server stores tokens only for the TikTok account you authorize, and only so it can make authenticated TikTok API calls for that account.

The local server currently exposes the following tools through its MCP registry. This list is the source of truth for the open-source package.

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

- tiktok_ads_get_campaigns- Retrieve campaigns for the advertiser account.
- tiktok_ads_get_campaign_details- Get details for a specific campaign.
- tiktok_ads_get_adgroups- Retrieve ad groups for a campaign.
- tiktok_ads_get_adgroup_details- Get details for a specific ad group.
- tiktok_ads_get_ads- Retrieve ads by campaign, ad group, ad ID, or status.
- tiktok_ads_get_ad_details- Get details for a specific ad.

- tiktok_ads_get_campaign_performance- Get campaign-level metrics.
- tiktok_ads_get_adgroup_performance- Get ad group-level metrics.
- tiktok_ads_get_ad_performance- Get ad-level metrics.
- tiktok_ads_get_audience_breakdown- Break down campaign, ad group, or ad performance by audience dimension.
- tiktok_ads_wasted_spend_audit- Run a read-only audit for spend and clicks without conversion signal.

- tiktok_ads_get_custom_audiences- List custom audiences.
- tiktok_ads_get_advertiser_info- Get account-level advertiser details such as currency, timezone, status, industry, country, and creation time.
- tiktok_ads_get_location_info- Resolve TikTok targeting location IDs.
- tiktok_ads_get_pixel_list- List pixels attached to the advertiser account.
- tiktok_ads_get_pixel_event_stats- Get pixel event activity for a date range.

Current MCP tools are only listed when they are wired to real OAuth, local token state, or TikTok Marketing API calls. This repository does not expose placeholder or mock tools.

- Broader GMV Max campaign coverage.
- Safe write operations for campaigns, ad groups, ads, and assets.
- Creative and asset management.
- Full async report lifecycle: create, status, and download.
- Targeting discovery and audience management.

Failed to spawn process: No such file or directory

The MCP client cannot find the command you configured.

- Use"command": "uv"ifuvis on the app's PATH.
- Otherwise use the full path, for example:

"command": "/Users/yourname/.local/bin/uv"

You are running the server with system Python instead of the project's environment.

"command": "uv", "args": ["--directory", "/path/to/tiktok-ads-mcp-server", "run", "python", "run_server.py"]

cd /path/to/tiktok-ads-mcp-server uv sync

can't open file '//run_server.py'

Your MCP client starteduv, but it did not run the command from the project directory.

Fix your MCP config to put the project directory in theuvarguments instead of relying oncwd:

"command": "uv", "args": ["--directory", "/path/to/tiktok-ads-mcp-server", "run", "python", "run_server.py"]

The server did not receiveTIKTOK_APP_IDorTIKTOK_APP_SECRET.

- Add both values underenvin your MCP client config.
- Restart your MCP client after changing the config.

OAuth succeeds, but tools still say unauthenticated

If you want to restart authentication, remove the token file and runtiktok_ads_loginagain:

Claude Desktop still shows the old error after config changes

Fully quit and reopen Claude Desktop. On macOS, closing the window is not always enough.

- Do not commit.env, token files, App Secrets, or OAuth codes.
- Keep~/.tiktok_ads_mcp/tokens.jsonprivate.
- Use a TikTok developer app with only the permissions you need.
- The current public MCP registry is read-only for TikTok Ads objects. Write operations are roadmap items and should be reviewed carefully before being exposed.

This project is licensed under the MIT License. SeeLICENSEfor details.

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

Interact with the Meta Ads API to access, analyze, and manage advertising campaigns.

Interact with Facebook and Instagram advertising data using the Meta Marketing API.

Manage digital advertising campaigns with AI-powered insights from Adspirer.com.

A managed AI marketing agent that plugs into all your AI tools. Ask about your marketing in natural language — get synthesized insights from GA4, Google Ads, Search Console, WooCommerce, and more.

Hosted MCP server that gives AI agents read and write access to your full marketing & ecommerce stack — Google Analytics, Search Console, Google & Meta Ads, Shopify, WooCommerce, Shopware, Slack and LinkedIn. 100+ tools across 10 connectors. BYOK, OAuth 2.1 with dynamic client registration.

MCP server for Walmart Connect Ads (Sponsored Search + Display) — automatic RSA-SHA256 signing, multi-region config, and bundled API docs.

MCP (Model Context Protocol) server for the Meta (Facebook) Ads API.

Paid Ads MCP Server - LinkedIn Ads and Google Ads

Paid Ads MCP lets marketers use AI tools to analyze Google Ads and LinkedIn Ads performance from live campaign data.

Run Facebook ad campaigns from any AI agent. Generate ads, research competitors, analyze markets, and launch Meta campaigns via API.

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "tiktok ads mcp server": {
            "tiktok-ads-mcp-server": {
                "command": "python",
                "args": [
                    "-m",
                    "venv",
                    "venv"
                ]
            }
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Time

A Model Context Protocol server that provides time and timezone conversion capabilities. It enables LLMs to get current time information and perform timezone…

88.2k
Productivity

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other

Reactive Resume

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

39.5k
Other