AdsMCP/tiktok-ads-mcp-server

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.
Hosted Option
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, AdsMCP provides a hosted remote MCP server:
AdsMCP Remote MCP Server Setup Guide
The rest of this README covers the local setup.
What This Server Does
- **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.
Prerequisites
You need:
- Python 3.10 or newer
- uv for 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
Install uv
macOS and Linux:
Windows PowerShell:
After installation, confirm that uv is available:
Find the absolute path to uv before configuring a desktop MCP client:
macOS and Linux:
Use the path returned by whereis uv or which uv as the MCP command value if your client cannot find uv by name.
Windows PowerShell:
Common paths are:
- macOS/Linux: /Users/ /.local/bin/uv
- Windows: C:\\Users\\ \\.local\\bin\\uv.exe
Install Locally
Clone the repository and install dependencies:
Find the absolute path to the project directory. You will use this path in the MCP config as the uv --directory value:
macOS and Linux:
Windows PowerShell:
Verify that the project environment can import MCP:
You should see:
Important: Use uv to Run the Server
Do not configure your MCP client to run this server with system python or python3 unless you have manually installed all dependencies into that exact Python environment.
Use this:
Not this:
Why: MCP desktop apps often launch a different Python than the one you use in your terminal. If that Python does not have the mcp package installed, the server exits with:
uv run makes the MCP client use this project's dependency environment.
Configure Claude Desktop
Claude Desktop reads its MCP server config from:
macOS:
Windows:
Linux paths vary by distribution and client package, but they are usually under:
macOS / Linux Config
Use uv --directory so the server starts from the project directory even if your MCP client does not apply cwd correctly.
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 --directory argument. If Claude cannot find uv, replace "uv" with the absolute path from whereis uv or which uv, such as "/Users/yourname/.local/bin/uv".
Windows Config
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 --directory argument, with each \ escaped as \\ in JSON:
If Claude cannot find uv on Windows, use the full path:
After editing the config, fully restart Claude Desktop.
TikTok App Setup
1. Go to the TikTok For Business Developer Portal.
2. Create or open a developer app.
3. Copy the App ID and App Secret.
4. Make sure the redirect URI configured in your TikTok app matches the redirect URI used by this server. By default, this project uses: