TikTok Ads MCP Server
TikTok Ads via MCP: 27 ferramentas de leitura e 277 métricas, além de 5 ferramentas de escrita que descrevem a alteração e a aplicam apenas em uma segunda chamada confirmada.
Documentação
tiktok-ads-mcp-server
Um servidor open-source do Model Context Protocol para a TikTok Business API. Ele permite que Claude, ChatGPT, Cursor ou qualquer cliente MCP leia e analise seus dados de publicidade do TikTok, e os altere se você escolher.
Você o executa. Seu token permanece na sua máquina. Nada é intermediado por terceiros.
npx -y @getmcpads/tiktok-ads-mcp-server
Também listado no MCP Registry como com.getmcpads/tiktok-ads, para que clientes que leem o registro possam instalá-lo pelo nome.
Prefere não executar você mesmo? getmcpads.com é a versão hospedada deste servidor, com TikTok Ads ao lado de Meta Ads, Google Ads, Pinterest Ads, GA4 e Search Console em um único endpoint, OAuth hospedado e relatórios entre plataformas. Mesmas ferramentas, mesmo modelo de segurança, sem configuração.
O que você obtém
| 27 ferramentas de leitura | Campanhas, grupos de anúncios, anúncios, criativos, públicos, pixels, eventos, Spark Ads, catálogos, diagnósticos de entrega |
| 5 ferramentas de escrita | Desativadas por padrão. Status de campanha e grupo de anúncios, orçamentos, criação de campanha. Cada uma mostra uma prévia antes de aplicar |
| 277 métricas | Incluindo as derivadas calculadas no lado do cliente |
| 16 dimensões | Com uma matriz de compatibilidade que detecta combinações inválidas antes de atingirem a API |
| 5 recursos | Catálogos ao vivo que o modelo pode ler: métricas, dimensões, regras de compatibilidade, 12 receitas de fluxo de trabalho |
| Pesquisa de palavras-chave | tiktok_search_keywords e tiktok_get_search_ads_maturity, para TikTok Search Ads |
| Leituras compatíveis com o futuro | tiktok_get_read_endpoint, tiktok_get_entities_raw, tiktok_get_report_raw alcançam endpoints que este servidor ainda não modela |
O planejador de consultas
O TikTok rejeita muitas combinações de métricas e dimensões, e suas mensagens de erro raramente dizem o porquê. Este servidor codifica a matriz de compatibilidade, então ele divide uma solicitação impossível em várias chamadas de API válidas e mescla os resultados em vez de falhar.
tiktok_validate_query permite que o modelo verifique uma combinação antes de gastar uma chamada nela.
Uma armadilha que este servidor resolve para você
O TikTok responde com HTTP 200 mesmo quando a chamada falhou. O campo aplicativo code é o que
decide. Um cliente que confia no status HTTP relata sucessos imaginários de volta ao modelo,
que então raciocina sobre dados que nunca foram retornados. Cada chamada aqui verifica code primeiro.
Como isso se compara ao servidor MCP oficial do TikTok
O TikTok oferece um servidor MCP oficial, anunciado no TikTok World '26 e hospedado em
business-api.tiktok.com/open_mcp/. É um produto sério, e é maior que este.
Aqui está uma comparação honesta.
| Servidor oficial do TikTok | Este servidor | getmcpads.com | |
|---|---|---|---|
| Hospedagem | Hospedado pelo TikTok, remoto | Você o hospeda. stdio, processo local | Hospedado para você |
| Caminho de dados | Através do endpoint do TikTok | Direto para a Business API. Sem intermediário | Através do nosso gateway |
| Ferramentas | ~400 planas, ou ~40 em modo em camadas | 32 (27 de leitura + 5 de escrita) | 32, mais 5 outras plataformas |
| Cobertura | Muito mais ampla | Relatórios, estrutura, criativos, públicos | Igual a este servidor |
| Escritas | Aplicadas diretamente | Prévia primeiro, aplicadas apenas em confirm: true | Prévia primeiro |
| Compatibilidade de métricas | Nenhuma documentada | Planejador de consultas divide solicitações incompatíveis | Mesmo planejador |
| HTTP 200 em falha | Tratado internamente | Verificado em cada chamada | Verificado |
| Auditável | Não | Sim. Apache-2.0, leia cada linha | Este servidor, auditado |
| Modificável | Não | Faça um fork | Não |
Seja claro sobre a troca. Se você quer a maior superfície possível da API do TikTok, o servidor oficial cobre muito mais endpoints do que este, e você deve usá-lo.
O que este servidor oferece em vez disso é um conjunto curado. O próprio TikTok oferece um modo em camadas que expõe cerca de 40 ferramentas em vez de 400, porque carregar centenas de definições de ferramentas preenche o contexto do modelo e faz com que ele escolha a ferramenta errada com mais frequência. 27 ferramentas de leitura bem descritas com um planejador ciente de compatibilidade é uma escolha de design deliberada, não uma lacuna.
Escolha o servidor oficial para amplitude, ou se você não precisa ver o código. Escolha este se você precisa que seus dados permaneçam na sua infraestrutura, quer auditar ou estender o que o modelo pode fazer, ou quer escritas que não possam ser disparadas na primeira chamada. Escolha getmcpads.com se você quer as capacidades deste servidor sem executá-lo, ou precisa de mais de uma plataforma de anúncios na mesma conversa.
Obtendo um token
O TikTok precisa de dois valores, não um: um token de acesso e o App ID ao qual ele pertence.
- Crie um aplicativo de desenvolvedor no portal de desenvolvedores do TikTok for Business.
- Anote o App ID e o App Secret da página do aplicativo.
- Autorize as contas de anunciante que você deseja alcançar. O TikTok concede acesso por anunciante, então uma conta que você pular aqui permanece invisível para o servidor, não importa o que o token permita.
- Complete o fluxo de autorização OAuth para trocar o
auth_coderetornado por um token de acesso. Os tokens de longa duração do TikTok não expiram em um cronograma fixo, mas são revogados quando a autorização é retirada. - Coloque o token em
TIKTOK_ACCESS_TOKENe o App ID emTIKTOK_APP_ID.
📖 Documentação da TikTok API for Business
Execute tiktok_health_check como sua primeira chamada. Ele verifica as credenciais, lista as
contas de anunciante que você pode realmente alcançar e relata o que está faltando, sem imprimir
seu token.
Quais permissões?
| Grupo de escopos | Quando você precisa |
|---|---|
| Escopos de relatórios e leitura | Sempre. Campanhas, grupos de anúncios, anúncios, insights |
| Escopos de gerenciamento de campanhas | Apenas se você definir TIKTOK_ENABLE_WRITES=1 |
| Escopos de Catálogo e Business Center | Opcional, para tiktok_get_shop_catalog_diagnostics |
Configuração
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
ou %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"tiktok-ads": {
"command": "npx",
"args": ["-y", "@getmcpads/tiktok-ads-mcp-server"],
"env": {
"TIKTOK_ACCESS_TOKEN": "your-token-here",
"TIKTOK_APP_ID": "your-app-id-here"
}
}
}
}
Reinicie o Claude Desktop. Pergunte a ele: "liste minhas contas de anunciante do TikTok".
Claude Code
claude mcp add tiktok-ads --env TIKTOK_ACCESS_TOKEN=your-token --env TIKTOK_APP_ID=your-app-id -- npx -y @getmcpads/tiktok-ads-mcp-server
Cursor
.cursor/mcp.json no seu projeto, com o mesmo formato da configuração do Claude Desktop acima.
A partir do código-fonte
git clone https://github.com/getmcpads-com/tiktok-ads-mcp-server.git
cd tiktok-ads-mcp-server
npm install && npm run build
cp .env.example .env # then fill in your credentials
npm start
Configuração
| Variável | Padrão | Significado |
|---|---|---|
TIKTOK_ACCESS_TOKEN | nenhum | Obrigatório. Seu token de acesso |
TIKTOK_APP_ID | nenhum | Obrigatório. O App ID ao qual o token pertence |
TIKTOK_APP_SECRET | nenhum | Opcional, para endpoints que exigem autenticação do aplicativo |
TIKTOK_ADVERTISER_ID | nenhum | Padrão opcional, evita passar em cada chamada |
TIKTOK_BC_ID | nenhum | ID do Business Center opcional |
TIKTOK_ENABLE_WRITES | não definido | Defina como 1 para registrar as 5 ferramentas de escrita |
LOG_LEVEL | info | debug, info, warn, error |
Verifique sua configuração a qualquer momento:
npm run doctor
Escritas e por que elas mostram prévia primeiro
As ferramentas de escrita estão desativadas por padrão. Ative-as com TIKTOK_ENABLE_WRITES=1.
Quando ativadas, cada ferramenta de escrita retorna uma prévia e não altera nada:
// tiktok_update_adgroup_budget { advertiserId: "7...", adGroupId: "1...", budget: 50 }
{
"applied": false,
"action": "tiktok_update_adgroup_budget",
"change": { "advertiser": "7...", "adGroup": "1...", "newBudget": 50,
"budgetMode": "BUDGET_MODE_DAY" },
"message": "Preview only, nothing was changed. Repeat the same call with confirm: true to apply this change to the live account."
}
Apenas uma segunda chamada carregando confirm: true toca a conta ao vivo.
Isso é deliberado. Um assistente compõe essas chamadas, e ele pode escolher o anunciante errado, a campanha errada ou a ordem de grandeza errada em um orçamento. Uma prévia obrigatória torna o erro visível antes de custar dinheiro e dá a um humano o ponto de parada que o protocolo não garante por conta própria.
Mais uma proteção: tiktok_create_campaign sempre cria a campanha DISABLE.
Não há opção de criá-la em execução.
| Ferramenta | O que ela altera |
|---|---|
tiktok_update_campaign_status / tiktok_update_adgroup_status | Pausar ou reativar |
tiktok_update_campaign_budget / tiktok_update_adgroup_budget | Orçamento, na moeda da conta |
tiktok_create_campaign | Cria uma campanha, sempre DISABLE |
Ferramentas
27 ferramentas de leitura
Descoberta e saúde
| Ferramenta | Propósito |
|---|---|
tiktok_health_check | Verifica credenciais e acesso do anunciante sem expor o token |
tiktok_list_advertisers | Cada conta de anunciante que o token pode alcançar |
tiktok_get_advertiser_info | Metadados da conta: nome, moeda, fuso horário, status |
Estrutura
| Ferramenta | Propósito |
|---|---|
tiktok_get_campaigns / tiktok_get_adgroups / tiktok_get_ads | Lista entidades e suas configurações |
tiktok_get_delivery_status | Estado de entrega e por que pode estar limitado |
Desempenho
| Ferramenta | Propósito |
|---|---|
tiktok_get_insights | A principal ferramenta de relatórios. Métricas, dimensões, planejamento ciente de compatibilidade |
tiktok_validate_query | Verifica uma combinação de métrica e dimensão antes de executá-la |
tiktok_get_report_raw | Campos de relatório nativos, sem aliases |
tiktok_get_async_report_status | Acompanha um relatório assíncrono de longa duração |
Criativos
| Ferramenta | Propósito |
|---|---|
tiktok_get_creatives | Texto do criativo do anúncio, IDs de mídia, URLs de destino |
tiktok_get_video_assets | Ativos de vídeo e seus metadados |
tiktok_get_creative_fatigue_recipes | Fluxos de trabalho para detectar fadiga criativa |
tiktok_get_spark_ads / tiktok_get_spark_organic_joins | Spark Ads e suas contrapartes orgânicas |
Públicos e segmentação
| Ferramenta | Propósito |
|---|---|
tiktok_get_audiences / tiktok_get_audience_details | Públicos personalizados e semelhantes |
tiktok_get_audience_overlap | Sobreposição entre públicos |
tiktok_get_targeting_catalog | Opções de segmentação disponíveis |
Search Ads
| Ferramenta | Propósito |
|---|---|
tiktok_search_keywords | Sugestões de palavras-chave para TikTok Search Ads |
tiktok_get_search_ads_maturity | O quão pronta uma conta está para Search Ads |
Comércio e sinais
| Ferramenta | Propósito |
|---|---|
tiktok_get_pixels / tiktok_get_events | Pixels e os eventos que eles recebem |
tiktok_get_shop_catalog_diagnostics | Saúde do catálogo e do feed de produtos |
Saídas de emergência
| Ferramenta | Propósito |
|---|---|
tiktok_get_read_endpoint | Chama um endpoint de leitura na lista de permissões diretamente |
tiktok_get_entities_raw | Leituras brutas de entidades com sua própria seleção de campos |
Elas existem para que um novo campo da API não exija um novo lançamento. Endpoints de mutação, endpoints OAuth e parâmetros de credenciais são bloqueados nesses caminhos, então um argumento elaborado não pode transformar uma ferramenta de leitura em uma escrita.
5 recursos
| URI | Conteúdo |
|---|---|
tiktok://manifest | O que este servidor expõe e seu modo atual |
tiktok://metrics | Todas as 277 métricas com categorias e formatos |
tiktok://dimensions | Todas as 16 dimensões e onde são válidas |
tiktok://compatibility | A matriz de compatibilidade |
tiktok://recipes | 12 fluxos de trabalho passo a passo |
Segurança
O servidor detém uma credencial que pode ler e, opcionalmente, modificar contas de anúncios ao vivo. Concretamente:
- O token nunca é registrado. A saída de depuração imprime
Access-Token: [redacted]. - As solicitações vão apenas para
business-api.tiktok.com, e apenas sob/open_api/v1.3/. Qualquer outro host ou caminho é recusado em vez de chamado. Coberto por testes. - Redirecionamentos são recusados uma vez que um token é anexado, para que um redirecionamento não possa encaminhar sua credencial para outro lugar.
- Endpoints de mutação e OAuth são bloqueados nos caminhos de leitura genéricos. Coberto por testes.
- Sem telemetria. O servidor não faz nenhuma chamada de rede além da TikTok Business API.
Você pode verificar isso pesquisando no código-fonte por
fetch.
Política completa e instruções de relatório: SECURITY.md.
Procurando uma versão gerenciada e multiplataforma?
Este servidor faz uma plataforma, na sua máquina, com seu token. Isso é proposital.
Se você prefere não executá-lo você mesmo, ou precisa de TikTok Ads ao lado de Meta Ads, Google Ads, Pinterest Ads, GA4 e Search Console em um único endpoint, com OAuth hospedado e relatórios entre plataformas, é isso que construímos em getmcpads.com.
Mesma filosofia, menos encanamento. Este projeto permanece open-source e independentemente útil de qualquer forma.
Contribuindo
Issues and pull requests são bem-vindos. Consulte CONTRIBUTING.md. Leia SECURITY.md antes de relatar qualquer problema relacionado à segurança.
Licença
Apache License 2.0. Consulte também NOTICE.
TikTok e TikTok for Business são marcas registradas da ByteDance Ltd. e suas afiliadas. Este projeto não é afiliado, endossado ou patrocinado pela TikTok ou ByteDance. É um cliente independente de uma API pública.