TikTok Ads MCP Server

O filme demonstra o getmcpads hospedado com dados de teste. Suas galerias criativas e a interface de Apps MCP pertencem ao produto hospedado. Este repositório fornece as ferramentas nativas independentes da API.

35 ferramentas de leitura · 29 ferramentas de escrita, desativadas por padrão.

Execute localmente com suas próprias credenciais da plataforma e um cliente que suporte stdio MCP, como Claude Desktop, Claude Code ou Cursor. Suas solicitações vão diretamente para a plataforma. Para conexões gerenciadas, incluindo configurações compatíveis com ChatGPT, use a opção hospedada.

Novidades

v2.0.0: Ferramentas nativas e atualização de segurança · 20 de setembro de 2026

• Preserve IDs exatos de 64 bits sem aspas nas respostas de leitura, escrita e verificação.
• Corrija a seleção de campos de campanha e os limites padrão de listagem.
• Atualize a validação nativa de escrita para orçamentos, agendamentos, segmentação e leitura de retorno. Adicione música de carrossel, prontidão de vídeo enviado, portfólio de CTA e ferramentas de identidade personalizada.
• Exija Node.js 22.12 ou mais recente e verifique Node 22/24 no CI.
• Atualize dependências vulneráveis e regenere o catálogo MCP.

Changelog completo · Detalhes de sincronização de fontes · Todas as versões

Notas de atualização

Requer Node.js 22.12 ou mais recente. O CI cobre Node 22 e 24. A versão 2.0.0 remove o suporte a Node 18 e 20. Leia os esquemas atuais das ferramentas antes de reutilizar argumentos salvos. As escritas permanecem opcionais e exigem confirmação explícita. Integrações criativas hospedadas e a interface de Apps MCP estão fora desta versão.

Instalar esta versão

Esta é uma versão de código-fonte do GitHub. As versões do npm e do Registro MCP são publicadas separadamente. Os comandos abaixo selecionam esta versão exata; exemplos sem fixação de versão npx mais adiante neste documento selecionam a versão atualmente disponível no npm.

git clone --branch v2.0.0 --depth 1 https://github.com/getmcpads-com/tiktok-ads-mcp-server.git
cd tiktok-ads-mcp-server
npm ci
npm run build

Configure seu cliente MCP para executar node com o caminho absoluto para dist/cli.js e as credenciais da plataforma documentadas abaixo.

Prefere uma conexão gerenciada? Use o TikTok Ads com o getmcpads hospedado. Conecte sua conta, selecione os dados que seu assistente pode acessar e use a conexão MCP hospedada. Consulte o site para recursos e planos atuais.

O que você obtém

35 ferramentas de leitura	Campanhas, grupos de anúncios, anúncios, criativos, públicos, pixels, eventos, Spark Ads, catálogos, diagnóstico de entrega
29 ferramentas de escrita	Desativadas por padrão. Status de campanhas e grupos de anúncios, orçamentos, criação de campanhas. 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 chegarem à 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 explicam o motivo. 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.

---

Obtendo um token

O TikTok precisa de dois valores, não um: um token de acesso e o App ID ao qual ele pertence.

1. Crie um aplicativo de desenvolvedor no portal de desenvolvedores do TikTok for Business.
2. Anote o App ID e o App Secret na página do aplicativo.
3. Autorize as contas de anunciante que você deseja acessar. O TikTok concede acesso por anunciante, então uma conta que você pular aqui permanece invisível para o servidor, independentemente do que o token permite.
4. Conclua o fluxo de autorização OAuth para trocar o auth_code retornado 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.
5. Coloque o token em TIKTOK_ACCESS_TOKEN e o App ID em TIKTOK_APP_ID.

📖 Documentação da API TikTok for Business

Execute tiktok_health_check como sua primeira chamada. Ela verifica as credenciais, lista as contas de anunciante que você pode realmente acessar e informa 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	Somente 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 opcional do Business Center
TIKTOK_ENABLE_WRITES	não definido	Defina como 1 para registrar as 29 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."
}

Somente uma segunda chamada contendo confirm: true toca a conta ao vivo.

Isso é deliberado. Um assistente compõe essas chamadas e 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 que ele custe 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

Todas as ferramentas estão listadas abaixo. Consulte server-card.json para esquemas completos de parâmetros e saídas.

35 ferramentas de leitura

| Ferramenta | Finalidade | | --- | --- | | `tiktok_health_check` | Verificação de saúde somente leitura para credenciais do TikTok, anunciantes acessíveis e informações do anunciante. | | `tiktok_list_advertisers` | Listar todas as contas de anunciante do TikTok acessíveis com o token atual. | | `tiktok_get_advertiser_info` | Obter informações detalhadas para contas específicas de anunciante do TikTok: moeda, fuso horário, status, saldo. | | `tiktok_get_campaigns` | Listar campanhas para uma conta de anunciante do TikTok. | | `tiktok_get_adgroups` | Ler a configuração completa do grupo de anúncios nativo, incluindo segmentação, referências de público personalizado/ semelhante e exclusões, geolocalização, idioma, idade/gênero, posicionamentos, interesses/comportamentos, orçamento e programação. | | `tiktok_get_targeting` | Ler a segmentação configurada do grupo de anúncios e referências de público: inclusões/exclusões personalizadas/semelhantes, geolocalização, idioma, idade/gênero, posicionamentos, interesses e comportamentos. | | `tiktok_get_audience_report` | Ler relatórios de desempenho de AUDIENCE do TikTok por idade ou gênero no nível de anunciante, campanha, grupo de anúncios ou anúncio, incluindo entrega de campanhas Smart+ elegíveis. | | `tiktok_get_ads` | Listar anúncios para um anunciante do TikTok. | | `tiktok_get_insights` | Consultar insights de desempenho de anúncios do TikTok usando o catálogo atual de métricas nativas/calculadas e planejamento de consultas. | | `tiktok_get_creatives` | Obter detalhes criativos (vídeo, imagem, texto) para anúncios específicos em uma conta de anunciante do TikTok. | | `tiktok_get_audiences` | Listar públicos personalizados e semelhantes para uma conta de anunciante do TikTok. | | `tiktok_search_keywords` | Obter sugestões de palavras-chave para TikTok Search Ads. | | `tiktok_validate_query` | Validar uma combinação de métrica/dimensão do TikTok ANTES de executar. | | `tiktok_get_pixels` | Listar pixels do TikTok e, quando as permissões permitirem, metadados de eventos de pixel para um anunciante. | | `tiktok_get_events` | Descobrir eventos de pixel/app ou diagnósticos de rastreamento acessíveis para um anunciante. | | `tiktok_get_delivery_status` | Agregar status de entrega/operation_status de campanha, grupo de anúncios e anúncio com diagnósticos simples. | | `tiktok_get_async_report_status` | Verificar o status de uma tarefa de relatório assíncrono do TikTok por taskId quando os endpoints de relatório assíncrono estiverem disponíveis. | | `tiktok_get_video_assets` | Retornar metadados de ativos de vídeo do TikTok vinculados a anúncios de ad/get e endpoints de material de vídeo quando disponíveis. | | `tiktok_get_spark_ads` | Retornar contexto de Spark Ads a partir de campos de anúncio quando disponível, com fallback conservador se campos específicos de Spark não forem suportados. | | `tiktok_get_audience_details` | Obter detalhes de público personalizado/semelhante/salvo onde os endpoints DMP do TikTok estiverem acessíveis. | | `tiktok_get_shop_catalog_diagnostics` | Diagnósticos somente leitura de TikTok Shop/catálogo/e-commerce. | | `tiktok_get_search_ads_maturity` | Diagnosticar a maturidade de TikTok Search Ads a partir de relatórios de palavras-chave/termos de pesquisa e endpoints opcionais de recomendação de palavras-chave. | | `tiktok_get_creative_fatigue_recipes` | Encontrar padrões prováveis de fadiga criativa a partir de relatórios diários no nível de anúncio e retornar receitas de atualização somente leitura. | | `tiktok_get_audience_overlap` | Diagnósticos somente leitura de sobreposição de público entre grupos de anúncios, públicos personalizados, públicos salvos e campos de segmentação. | | `tiktok_get_spark_organic_joins` | Unir campos de Spark Ads acessíveis com relatórios de página/publicação pagos e endpoints opcionais de identidade/publicação orgânica quando as permissões permitirem. | | `tiktok_list_ad_videos` | Listar toda a biblioteca de vídeos do anunciante (arquivo/vídeo/anúncio/pesquisa): nome do arquivo, duração, dimensões, assinatura e URLs públicas de pré-visualização e capa. | | `tiktok_list_ad_images` | Listar toda a biblioteca de imagens do anunciante (arquivo/imagem/anúncio/pesquisa): nome do arquivo, dimensões, assinatura, usabilidade em carrossel e uma URL de imagem servida publicamente assinada por aproximadamente trinta dias (image_url_expires_at dá o instante exato). | | `tiktok_get_asset_urls` | Re-resolver URLs novas e publicamente buscáveis para ativos específicos da biblioteca do TikTok (arquivo/vídeo/anúncio/info e arquivo/imagem/anúncio/info). | | `tiktok_get_entities_raw` | Listar campanhas, grupos de anúncios ou anúncios do TikTok com campos nativos selecionados pelo chamador, filtragem, ordenação e paginação. | | `tiktok_get_report_raw` | Executar um relatório síncrono nativo BASIC ou AUDIENCE do TikTok com dimensões e métricas selecionadas pelo chamador. | | `tiktok_get_targeting_catalog` | Ler catálogos de segmentação e planejamento do TikTok: locais, idiomas, interesses, comportamentos, hashtags, ideias/saúde de palavras-chave de Search Ads, dispositivos, operadoras, tags contextuais, exclusões de conteúdo e fusos horários. | | `tiktok_get_read_endpoint` | Saída de escape avançada somente GET da TikTok Business API para endpoints JSON de leitura documentados ainda não modelados por uma ferramenta MCP especializada. | | `tiktok_get_carousel_music` | Obter recomendações de música do TikTok exatamente para as imagens enviadas em um anúncio de imagem padrão, não-catálogo (um cartão) ou carrossel. | | `tiktok_get_uploaded_video` | Ler um vídeo enviado da biblioteca de mídia deste anunciante. | | `tiktok_get_write_context` | Ler a entidade exata do TikTok, configurações do pai e moeda/fuso horário do anunciante antes de editar ou construir uma nova configuração. |

29 ferramentas de escrita

Desabilitadas por padrão. Chamadas em pré-visualização, a menos que explicitamente confirmadas. Verifique a configuração e o esquema exato antes do uso.

Ferramenta	Finalidade
tiktok_create_cta_portfolio	Criar um portfólio de CTA dinâmico a partir das recomendações aprovadas exatas retornadas por creative/cta/recommend para este anunciante.
tiktok_create_custom_identity	Criar uma identidade publicitária CUSTOMIZED_USER de propriedade do anunciante para Pangle ou Global App Bundle.
tiktok_create_campaign_advanced	Criar campanha clássica do TikTok DESATIVADA.
tiktok_update_campaign_configuration	Atualizar campanha clássica do TikTok.
tiktok_create_adgroup	Criar grupo de anúncios clássico do TikTok DESATIVADO.
tiktok_update_adgroup_configuration	Atualizar grupo de anúncios clássico do TikTok.
tiktok_create_ads	Criar anúncios clássicos do TikTok DESATIVADOS (vídeo, imagem, carrossel ou conteúdo Spark autorizado).
tiktok_update_ads	Atualizar anúncios clássicos do TikTok (vídeo, imagem, carrossel ou conteúdo Spark autorizado).
tiktok_create_smart_plus_campaign	Criar campanha Smart+ atualizada do TikTok DESATIVADA.
tiktok_update_smart_plus_campaign	Atualizar campanha Smart+ atualizada do TikTok.
tiktok_create_smart_plus_adgroup	Criar grupo de anúncios Smart+ atualizado do TikTok DESATIVADO.
tiktok_update_smart_plus_adgroup	Atualizar grupo de anúncios Smart+ atualizado do TikTok.
tiktok_create_smart_plus_ad	Criar anúncios Smart+ atualizados do TikTok DESATIVADOS (vídeo, imagem, carrossel ou conteúdo Spark autorizado).
tiktok_update_smart_plus_ad	Atualizar anúncios Smart+ atualizados do TikTok (vídeo, imagem, carrossel ou conteúdo Spark autorizado).
tiktok_update_ad_status	Pausar ou reativar exatamente um anúncio clássico.
tiktok_update_smart_plus_campaign_status	Pausar ou reativar exatamente uma campanha Smart+.
tiktok_update_smart_plus_adgroup_status	Pausar ou reativar exatamente um grupo de anúncios Smart+.
tiktok_update_smart_plus_ad_status	Pausar ou reativar exatamente um anúncio Smart+.
tiktok_update_smart_plus_material_status	Pausar ou reativar materiais criativos selecionados dentro de um anúncio Smart+ atualizado.
tiktok_rename_campaign	Renomear uma campanha clássica do TikTok.
tiktok_rename_adgroup	Renomear um grupo de anúncios clássico do TikTok.
tiktok_rename_ad	Renomear um anúncio clássico do TikTok.
tiktok_upload_ad_image	Importar uma imagem de uma URL de mídia HTTPS pública ou arquivo base64 (até 5 MiB).
tiktok_upload_ad_video	Importar um vídeo de uma URL de mídia HTTPS pública ou arquivo base64 (até 5 MiB).
tiktok_update_campaign_status	Pausar ou reativar uma campanha do TikTok.
tiktok_create_campaign	Criar uma campanha do TikTok.
tiktok_update_campaign_budget	Alterar o orçamento de uma campanha do TikTok, na moeda da conta.
tiktok_update_adgroup_status	Pausar ou reativar um grupo de anúncios do TikTok.
tiktok_update_adgroup_budget	Alterar o orçamento de um grupo de anúncios do TikTok.

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 mantém uma credencial que pode ler e, opcionalmente, modificar contas de anúncios ativas. 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 somente 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 genéricos de leitura. 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?

Experimente o TikTok Ads hospedado se quiser usar esta fonte sem operar um servidor local. getmcpads também conecta publicidade, Search Console e GA4 por meio de uma única URL MCP. A disponibilidade da fonte e os limites do plano estão listados no site; conectar uma conta ainda é necessário.

1. Siga o guia de conexão do TikTok Ads.
2. Selecione a conta ou propriedade que seu assistente pode ler.
3. Conecte Claude, ChatGPT ou Codex.
4. Tente uma revisão somente leitura: “Compare tendências de entrega e conversão de campanhas em períodos completos. Indique dados ausentes e não altere nada.”

Veja o catálogo atual de ferramentas hospedadas e preços antes de escolher um plano pago. Este adaptador Apache 2.0 permanece independentemente útil com suas próprias credenciais.

---

Contribuindo

Issues e pull requests são bem-vindos. Veja CONTRIBUTING.md. Leia SECURITY.md antes de relatar qualquer coisa relacionada à segurança.

Licença

Apache License 2.0. Veja 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.

Contratos MCP e pacote de desktop

Cada ferramenta declara anotações de leitura/escrita, descrições de parâmetros e um esquema de saída estruturado. Chamadas bem-sucedidas expõem o payload como structuredContent.result; erros retêm isError: true. O cartão do servidor gerado contém apenas definições.

Execute npm run bundle -- /path/to/output para construir um pacote de desktop .mcpb a partir do catálogo atual. As credenciais são inseridas localmente durante a instalação. As ferramentas de escrita permanecem desabilitadas, a menos que explicitamente habilitadas.

Mais da getmcpads

Meta Ads · Google Ads · Google Analytics 4 · Google Search Console · Pinterest Ads · X Ads

Mantido por Emmanuel na getmcpads. Perguntas: hello@getmcpads.com.