TikTok Ads Library MCP Server
Search and analyze TikTok Ad Library ads, including creative video/image insights and cached media management.
Search TikTok’s public Ad Library by exact advertiser name or keyword, with pagination.
Get full ad details: landing page, country targeting, engagement metrics, and a fresh video URL.
Analyze ad images for visual elements, text, colors, people, brand elements, and composition.
Analyze video ads with Gemini for hooks, scene-by-scene storytelling, on-screen text, audio/voiceover, pacing, and brand messaging.
Compare advertisers’ messaging and creative strategies using ad data and analysis outputs.
Inspect cache statistics and storage usage.
Search previously analyzed cached media by brand, colors, people, or media type.
Clean up old cached media files to free disk space.
Provides video ad analysis using Google Gemini to generate scene-by-scene creative insights.
Enables searching and analyzing TikTok's public Ad Library, including advertiser search, ad details, and creative analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TikTok Ads Library MCP Server What's the hook in the first 3 seconds of each of Duolingo's TikTok video ads?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

TikTok Ads Library MCP Server
Proxy (useproxy.dev) is the free hosted version of this server. One connection gives ChatGPT, Claude, Cursor and any MCP client live ads from the Meta, Google, LinkedIn and TikTok (EU) ad libraries, with no API keys and 20 free credits a day. Use it in 2 minutes →
This repo is the open-source, self-hosted TikTok server, for personal use and tinkering. It covers one platform, you pay ScrapeCreators for every call (about $1.88 per 1,000 after 100 free credits), and it doesn't get every feature hosted Proxy has. For client work or a team,use hosted Proxy.
This is a Model Context Protocol (MCP) server for the TikTok Ad Library.
With this you can search TikTok's public ad library for any advertiser, see the creatives they're running and analyze their advertising. You can analyze ad images and cover frames, analyze video ads with scene-by-scene insights, compare advertisers' strategies, and get insights into what's working in their campaigns.
Here's an example of what you can do when it's connected to Claude.
Hosted Version (Recommended)
The easiest way to use the TikTok Ads Library MCP is the hosted version from Proxy (useproxy.dev). No API keys, no Gemini key, no Python, no server to run — just connect and start querying.
⚡ Zero setup — nothing to install, configure, or maintain
🔑 No API keys — skip the ScrapeCreators and Gemini keys entirely
🔌 Works everywhere — ChatGPT, Claude, Cursor, Manus, and anywhere else that supports MCP
🚀 Always up to date — new tools and fixes ship automatically
👉 Get started for free at useproxy.dev →
Prefer to run it yourself? The full self-host setup is documented below.
Hosted vs. Self-Host
Hosted: Proxy (useproxy.dev) | Self-host (this repo) | |
Ad libraries | Meta, Google, LinkedIn and TikTok (EU) in one server | TikTok (EU) only |
Cost | Free for 20 credits a day; paid plans for more | ScrapeCreators credits (about $1.88 per 1,000 calls) plus Gemini usage for video |
API keys | None, sign in with OAuth | ScrapeCreators, plus Gemini for video |
Competitor discovery and competitive brief | ✅ | ❌ |
Inline ad carousel | ✅ | ❌ |
ChatGPT and claude.ai | ✅ (ChatGPT app and Claude connector) | ❌ (they need a public OAuth server) |
Claude Desktop, Claude Code, Cursor | ✅ | ✅ |
Setup and updates | None, managed for you | Python or Docker; |
Best for | Marketers, agencies, teams | Developers who want to change the code |
Need another platform? The other self-hosted servers: Facebook · Google · LinkedIn. Or get all four in one connection with hosted Proxy. Comparison and setup for all four: useproxy.dev/self-host.
Related MCP server: Facebook Ads Library MCP Server
Example Prompts
How many TikTok ads is 'Anysphere' running? What's their split across video and image?What's the hook in the first 3 seconds of each of 'Duolingo's TikTok video ads?Analyze the video ads from 'Gymshark' and tell me which read as creator-style UGC vs polished brand production.Compare the messaging and creative style between 'Anysphere' and 'Notion Labs' on TikTok. Give it a nice forwardable summary.Installation
Prerequisites
Python 3.12+
Anthropic Claude Desktop app (or Cursor)
Pip (Python package manager), install with
python -m pip installAn API key for an ads data provider, set as
SCRAPECREATORS_API_KEY(see configuration below)A Google Gemini API key for video analysis (TikTok ads are overwhelmingly video, so this is effectively required)
Prefer not to deal with API keys? See the Hosted Version above to skip setup entirely.
Quick Install (Recommended)
Clone and run the install script
git clone https://github.com/proxy-intell/tiktok-ads-library-mcp.git cd tiktok-ads-library-mcp # For macOS/Linux: ./install.sh # For Windows: install.batConfigure your API keys
Edit the
.envfile that was created and add your API keys:Set your ads data API key as
SCRAPECREATORS_API_KEYGet your Gemini API key at Google AI Studio
Follow the displayed MCP configuration
The install script will show you the exact configuration to add to Claude Desktop or Cursor.
Manual Install
If you prefer to install manually:
Clone this repository
git clone https://github.com/proxy-intell/tiktok-ads-library-mcp.git cd tiktok-ads-library-mcpInstall dependencies
pip install -r requirements.txtConfigure API keys
Copy the template and configure your API keys:
cp .env.template .env # Then edit .env with your actual API keysTo obtain API keys:
Set your ads data API key as
SCRAPECREATORS_API_KEYin the.envfileGet a Google Gemini API key here
Connect to the MCP server
Add the MCP server configuration to your Claude Desktop or Cursor config:
{ "mcpServers": { "tiktok_ads_library": { "command": "/usr/local/opt/python@3.13/bin/python3", "args": [ "{{PATH_TO_PROJECT}}/tiktok-ads-library-mcp/mcp_server.py" ] } } }Replace
{{PATH_TO_PROJECT}}with the full path to where you cloned this repository.Note: API keys are automatically loaded from the
.envfile. Command line arguments are still supported and take priority over environment variables if provided.For Claude Desktop:
Save this as
claude_desktop_config.jsonin your Claude Desktop configuration directory at:~/Library/Application Support/Claude/claude_desktop_config.jsonFor Cursor:
Save this as
mcp.jsonin your Cursor configuration directory at:~/.cursor/mcp.jsonRestart Claude Desktop / Cursor
Open Claude Desktop and you should now see the TikTok Ads Library as an available integration.
Or restart Cursor.
Deploy to the cloud
Run it as a remote MCP server so Cursor, Claude Code or Claude Desktop can reach it from anywhere.
Click the button and enter your
SCRAPECREATORS_API_KEY(andGEMINI_API_KEYfor video). Render generatesMCP_AUTH_TOKENfor you.Your endpoint is
https://<your-service>.onrender.com/mcp/. Every request needs the headerAuthorization: Bearer <MCP_AUTH_TOKEN>.Claude Code:
claude mcp add --transport http tiktok-ads https://<your-service>.onrender.com/mcp/ --header "Authorization: Bearer <MCP_AUTH_TOKEN>"
Any Docker host works the same way:
docker build -t tiktok-ads-library-mcp .
docker run -p 8000:8000 -e MCP_TRANSPORT=http -e MCP_AUTH_TOKEN=<long-random-string> -e SCRAPECREATORS_API_KEY=<key> tiktok-ads-library-mcpThe server refuses to start in HTTP mode without an MCP_AUTH_TOKEN of 16+ characters, so nobody else can spend your credits. Or skip all of this: hosted Proxy is already running.
Usage data
The server sends an anonymous ping to the maintainers on each tool call: the tool name, this repo's name, a call count and a random install ID stored in ~/.config/proxy-ads-mcp/. It never sends tool arguments, results, API keys or anything about you. Turn it off with PROXY_TELEMETRY=0 (or DO_NOT_TRACK=1). It tells us which tools people use so we know what to fix. Code: src/telemetry.py.
Every so often (the 25th call, then every 100th) a tool result includes a one-line tip about hosted Proxy.
Technical Details
Claude sends requests to the Python MCP server
The MCP server queries the ads data API for TikTok Ad Library data
Data flows back through the chain to Claude
TikTok Ads
This server connects to TikTok's public Ad Library:
Advertiser names are legal entity names. TikTok indexes advertisers by their registered business name, and matching is exact and case-sensitive. Search
Anysphere, notCursor. If a brand name returns nothing, try the legal entity behind it.Video-first. Most TikTok ads are video.
analyze_ad_videois where the real signal is;analyze_ad_imagemainly covers cover frames and the occasional static creative.Media URLs expire. TikTok's CDN URLs are signed and go dead within minutes. Always pass
ad_idtoanalyze_ad_video— the server then fetches a fresh URL itself and caches the result under the ad id, so repeat analysis of the same ad is free.Coverage is EU-weighted. TikTok's public ad library is driven by EU transparency obligations, so delivery in EU markets is what's most reliably indexed.
Available MCP Tools
This MCP server provides tools for interacting with TikTok Ad Library objects:
Tool Name | Description |
| Searches the TikTok Ad Library by advertiser name or keyword, with automatic pagination |
| Gets full detail for a specific ad — landing page, country targeting, engagement, fresh video URL |
| Downloads and analyzes ad images for visual elements, text, colors, and composition |
| Downloads and analyzes ad videos using Gemini AI for scene-by-scene creative insights |
| Gets statistics about cached media (images and videos) and storage usage |
| Searches previously analyzed media by brand, colors, people, or media type |
| Cleans up old cached media files to free disk space |
Troubleshooting
Common Issues
API Key Not Found Error:
Ensure your
.envfile is in the project root directoryIf you don't have a
.envfile, copy it from the template:cp .env.template .envCheck that your API keys are correctly formatted without quotes
Verify the
.envfile containsSCRAPECREATORS_API_KEY=your_key_hereFor video analysis, ensure
GEMINI_API_KEY=your_key_hereis also added
Search Returns No Ads:
TikTok matches advertiser names exactly and case-sensitively — try the registered business name rather than the brand (e.g.
Anyspherefor Cursor)The advertiser may not have delivered ads in markets covered by TikTok's public library
Video Analysis Not Working:
Confirm you have a valid Google Gemini API key in your
.envfilePass
ad_idrather thanmedia_url. Avideo_urlcopied from an earlier search response has almost certainly expired
MCP Server Connection Issues:
Verify the path in your MCP configuration points to the correct location
Make sure you've installed all dependencies with
pip install -r requirements.txtRestart Claude Desktop/Cursor after configuration changes
For additional Claude Desktop integration troubleshooting, see the MCP documentation. The documentation includes helpful tips for checking logs and resolving common issues.
Tests
The response parsing has a self-check that runs without network access or API keys:
python3 test_parsing.pyFAQ
What is the easiest way to use the TikTok Ads Library MCP? The easiest way is the hosted version from Proxy (useproxy.dev). It requires no API keys, no installation, and no server — you connect it to ChatGPT, Claude, Cursor, or any MCP client and start querying immediately. You can start for free.
Do I need an API key to use this MCP?
Only if you self-host. The hosted version at useproxy.dev handles all data access for you, so no ScrapeCreators or Gemini keys are needed. Self-hosting requires a SCRAPECREATORS_API_KEY (and a Gemini key for video analysis).
Why does searching a brand name return nothing?
TikTok's ad library indexes advertisers by registered business name with exact, case-sensitive matching. Search the legal entity (e.g. Anysphere) rather than the product name (Cursor).
Which MCP clients does it work with? The hosted version works with ChatGPT, Claude (desktop, web and mobile), Cursor, Manus and any other MCP client. The self-hosted version works with local MCP clients such as Claude Desktop, Claude Code and Cursor, or as a remote server with a bearer token (see Deploy to the cloud).
Is there a free version? Yes — the hosted version from Proxy offers a free tier so you can start analyzing ads without any setup.
Should I self-host or use the hosted version? Use the hosted version if you just want fast, reliable access to TikTok Ad Library data with zero maintenance — this fits most users. Self-host only if you want to modify or extend the server code yourself.
Feedback
Your feedback will be massively appreciated. Please tell us which features on that list you like to see next or request entirely new ones.
Related
Proxy hosted MCP: all four ad libraries in one hosted server, OAuth, no keys
Facebook Ads Library MCP (self-hosted)
Google Ads Library MCP (self-hosted)
LinkedIn Ads Library MCP (self-hosted)
License
This project is licensed under the MIT License.
Made with ❤️ by the team at Proxy.
Available Tools
7 toolsanalyze_ad_imageARead-only
REQUIRED for analyzing images from TikTok ads. Download and analyze ad images (cover frames and static creatives) to extract visual elements, text content, colors, people, brand elements, and composition details. This tool should be used for EVERY image URL returned by search_tiktok_ads when doing comprehensive analysis. Uses intelligent caching so multiple image analysis calls are efficient and cost-free.
Inputs: media_url (required), ad_id, brand_name.
analyze_ad_videoARead-only
REQUIRED for analyzing video ads from TikTok. Downloads and analyzes ad videos using Gemini's video understanding to extract the hook, scene-by-scene storytelling, on-screen text, audio/voiceover, pacing and brand messaging. ALWAYS pass ad_id — TikTok CDN URLs are signed and expire within minutes, and ad_id lets the server fetch a fresh URL and cache results stably across sessions. Uses intelligent caching for efficiency.
Inputs: ad_id, media_url, brand_name.
cleanup_media_cacheA
REQUIRED for cleaning up old cached media files (images and videos) and freeing disk space. Use this tool when users want to remove old cached media, clean up storage space, or when cache becomes too large. Essential for cache maintenance and storage management.
Inputs: max_age_days.
get_cache_statsARead-only
REQUIRED for checking media cache status and storage usage. Use this tool when users ask about cache statistics, storage space used by cached media (images and videos), or how many files have been analyzed and cached. Essential for cache management and monitoring.
Inputs: no named parameters.
get_tiktok_ad_detailsARead-only
Get detailed information about a specific TikTok ad including the full creative, landing page, country targeting, engagement metrics and a fresh playable video URL. Use this with an ad_id from search_tiktok_ads. Essential for analyzing ad content and extracting media URLs for visual analysis.
Inputs: ad_id (required).
search_cached_mediaARead-only
REQUIRED for finding previously analyzed ad media (images and videos) in cache. Use this tool when users want to search for cached media by brand name, find media with people, search by colors, or filter by media type. Essential for retrieving past analysis results without re-downloading media.
Inputs: limit, brand_name, has_people, media_type, +1 more.
search_tiktok_adsARead-only
Search TikTok's public Ad Library for the ads an advertiser is running. Use the registered advertiser name (exact, case-sensitive — e.g. 'Anysphere', not 'Cursor'), or a keyword to discover ads by topic. Returns ad ids, run dates, spend/impression bands and media URLs. For complete analysis of visual elements, colors, design, or creative content, you MUST also use analyze_ad_video (passing ad_id) or analyze_ad_image on the media returned by each ad.
Inputs: query (required), limit, cursor.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: search finds ads, get details retrieves metadata, analyze tools process video or image content, and cache tools manage storage. No two tools overlap in function.
All tool names follow a consistent verb_noun snake_case pattern: search_tiktok_ads, analyze_ad_video, cleanup_media_cache, etc. The naming style is uniform and predictable.
With 7 tools, the set is well-scoped for TikTok ad search, analysis, and cache management. Each tool earns its place without redundancy or bloat.
The surface covers the full workflow: searching ads, retrieving details, analyzing video and image creatives, and managing cached results. No obvious missing operations are apparent.
Maintenance
Related MCP Connectors
EU TikTok Ad Library by advertiser or keyword: ad dates, reach, creatives and lifecycle status.
Meta Ad Library and Google Ads Transparency video ads, plus AI teardowns and shot-by-shot analysis.
Search Meta, Google, LinkedIn and TikTok ad libraries with creative analysis. 50 free searches.
Public social, ad library and Google Maps data: TikTok, Instagram, YouTube, X, Facebook and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceSearches and analyzes competitor ads and content across Meta, Google, Instagram, TikTok, and YouTube with AI-powered creative analysis and cross-platform brand discovery.1MIT
- AlicenseAqualityBmaintenanceEnables searching and analyzing Facebook's public ads library for any brand, including ad images, text, and video analysis.822 npm326MIT
- AlicenseAqualityCmaintenanceEnables searching and analyzing LinkedIn's public ad library for any company, including ad creatives, targeting, and competitive insights. Supports image and video analysis, company comparisons, and detailed ad lookups via natural language.713 npm3MIT
- AlicenseNot gradedqualityDmaintenanceEnables users to search the Google Ads Transparency Center for company ads, inspect ad details and variations, analyze images and videos, and compare competitor advertising strategies.10 npmMIT