TikTok Ads MCP Server

TikTok Ads MCP Server

Um servidor local de Model Context Protocol (MCP) para integração com a API de TikTok Ads. Ele permite que clientes MCP, como o Claude Desktop, se conectem ao TikTok Ads, autentiquem-se com um aplicativo TikTok Business e usem ferramentas somente leitura para consulta de campanhas, inspeção de grupos de anúncios e anúncios, relatórios de desempenho, detalhamentos de público, informações do anunciante, pixels e locais de segmentação.

O Que Este Servidor Faz

• Autenticação: Inicie e conclua o OAuth do TikTok Ads a partir de um cliente MCP.
• Consulta de campanhas: Liste campanhas, inspecione detalhes de campanhas, liste grupos de anúncios e inspecione anúncios.
• Análise de desempenho: Obtenha métricas de campanha, grupo de anúncios, anúncio e público para intervalos de datas comuns.
• Dados de público e conta: Recupere públicos personalizados, informações do anunciante, IDs de locais, pixels e estatísticas de eventos de pixel.
• Operação somente leitura: O registro público de ferramentas MCP não expõe criação de campanhas, criação de grupos de anúncios, upload de criativos ou outras operações de escrita.

Opção Hospedada

Este repositório é para usuários que desejam executar um servidor TikTok Ads MCP local.

Se você não quiser instalar Python, gerenciar dependências ou configurar um aplicativo de desenvolvedor TikTok, o AdsMCP fornece um servidor MCP remoto hospedado:

Guia de Configuração do Servidor MCP Remoto AdsMCP

O restante deste README cobre a configuração local.

Pré-requisitos

Você precisa de:

• Python 3.10 ou mais recente
• uv para gerenciamento de dependências
• Uma conta TikTok For Business com acesso à API de Marketing
• Um aplicativo de desenvolvedor TikTok com um App ID e App Secret
• Um cliente MCP que suporte servidores stdio locais, como o Claude Desktop

Instalar uv

macOS e Linux:

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

Windows PowerShell:

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

Após a instalação, confirme que uv está disponível:

uv --version

Encontre o caminho absoluto para uv antes de configurar um cliente MCP de desktop:

macOS e Linux:

whereis uv
which uv

Use o caminho retornado por whereis uv ou which uv como o valor de command do MCP se o seu cliente não conseguir encontrar uv pelo nome.

Windows PowerShell:

where.exe uv

Caminhos comuns são:

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

Instalar Localmente

Clone o repositório e instale as dependências:

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

Encontre o caminho absoluto para o diretório do projeto. Você usará este caminho na configuração do MCP como o valor de uv --directory:

macOS e Linux:

pwd

Windows PowerShell:

Get-Location

Verifique se o ambiente do projeto pode importar o MCP:

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

Você deve ver:

ok

Importante: Use uv para Executar o Servidor

Não configure seu cliente MCP para executar este servidor com python ou python3 do sistema, a menos que você tenha instalado manualmente todas as dependências nesse ambiente Python exato.

Use isto:

uv run python run_server.py

Não isto:

python run_server.py
python3 run_server.py

Por quê: Aplicativos de desktop MCP frequentemente iniciam um Python diferente daquele que você usa no seu terminal. Se esse Python não tiver o pacote mcp instalado, o servidor sai com:

No module named 'mcp'

uv run faz o cliente MCP usar o ambiente de dependências deste projeto.

Configurar o Claude Desktop

O Claude Desktop lê a configuração do servidor MCP de:

macOS:

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

Windows:

%APPDATA%\\Claude\\claude_desktop_config.json

Os caminhos no Linux variam por distribuição e pacote do cliente, mas geralmente ficam em:

~/.config/Claude/

Configuração macOS / Linux

Use uv --directory para que o servidor inicie a partir do diretório do projeto, mesmo que seu cliente MCP não aplique cwd corretamente.

Para preencher "/absolute/path/to/tiktok-ads-mcp-server", abra um terminal no repositório clonado e execute:

pwd

Use o valor impresso como o argumento --directory. Se o Claude não conseguir encontrar uv, substitua "uv" pelo caminho absoluto de whereis uv ou which uv, como "/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"
      }
    }
  }
}

Configuração Windows

Use barras invertidas escapadas em caminhos JSON. Para encontrar o caminho do projeto, abra o PowerShell no repositório clonado e execute:

Get-Location

Use o valor impresso como o argumento --directory, com cada \ escapado como \\ no 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"
      }
    }
  }
}

Se o Claude não conseguir encontrar uv no Windows, use o caminho completo:

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

Após editar a configuração, reinicie completamente o Claude Desktop.

Configuração do Aplicativo TikTok

1. Vá para o Portal do Desenvolvedor TikTok For Business.
2. Crie ou abra um aplicativo de desenvolvedor.
3. Copie o App ID e o App Secret.
4. Certifique-se de que o URI de redirecionamento configurado no seu aplicativo TikTok corresponda ao URI de redirecionamento usado por este servidor. Por padrão, este projeto usa:

https://adsmcp.com

5. Adicione o App ID e o App Secret à configuração do seu cliente MCP em env.

Fluxo de Autenticação

Uma vez que o servidor MCP esteja conectado:

1. Execute tiktok_ads_login a partir do seu cliente MCP.
2. Abra a URL de autorização retornada pela ferramenta.
3. Aprove o acesso no TikTok.
4. Copie o parâmetro code da URL de redirecionamento.
5. Execute tiktok_ads_complete_auth com esse código.
6. Execute tiktok_ads_auth_status para confirmar que a conta está autenticada.

Armazenamento e Segurança de Tokens

Após a conclusão do OAuth, os tokens de acesso e atualização do TikTok são armazenados localmente em:

~/.tiktok_ads_mcp/tokens.json

Este arquivo é o que permite que o servidor MCP local chame a API de Marketing do TikTok após a autenticação. Trate-o como uma senha:

• Não o envie para o Git nem o compartilhe em relatórios de problemas.
• Mantenha-o na sua própria máquina e proteja-o com as permissões normais da sua conta do sistema operacional.
• Remova-o se quiser desconectar o servidor local da sua conta TikTok.

O servidor local armazena tokens apenas para a conta TikTok que você autoriza, e somente para que possa fazer chamadas autenticadas à API do TikTok para essa conta.

Ferramentas Disponíveis

O servidor local atualmente expõe as seguintes ferramentas através do seu registro MCP. Esta lista é a fonte da verdade para o pacote de código aberto.

Autenticação

• tiktok_ads_login - Inicie a autenticação OAuth do TikTok Ads.
• tiktok_ads_complete_auth - Conclua o OAuth usando o código de autorização.
• tiktok_ads_auth_status - Verifique o status atual de autenticação.
• tiktok_ads_switch_ad_account - Alterne para uma conta de anunciante diferente.

Gerenciamento de Campanhas

• tiktok_ads_get_campaigns - Recupere campanhas para a conta do anunciante.
• tiktok_ads_get_campaign_details - Obtenha detalhes de uma campanha específica.
• tiktok_ads_get_adgroups - Recupere grupos de anúncios para uma campanha.
• tiktok_ads_get_adgroup_details - Obtenha detalhes de um grupo de anúncios específico.
• tiktok_ads_get_ads - Recupere anúncios por campanha, grupo de anúncios, ID do anúncio ou status.
• tiktok_ads_get_ad_details - Obtenha detalhes de um anúncio específico.

Desempenho e Análise

• tiktok_ads_get_campaign_performance - Obtenha métricas em nível de campanha.
• tiktok_ads_get_adgroup_performance - Obtenha métricas em nível de grupo de anúncios.
• tiktok_ads_get_ad_performance - Obtenha métricas em nível de anúncio.
• tiktok_ads_get_audience_breakdown - Detalhe o desempenho de campanha, grupo de anúncios ou anúncio por dimensão de público.
• tiktok_ads_wasted_spend_audit - Execute uma auditoria somente leitura para gastos e cliques sem sinal de conversão.

Criativo e Público

• tiktok_ads_get_custom_audiences - Liste públicos personalizados.
• tiktok_ads_get_advertiser_info - Obtenha detalhes do anunciante em nível de conta, como moeda, fuso horário, status, setor, país e tempo de criação.
• tiktok_ads_get_location_info - Resolva IDs de locais de segmentação do TikTok.
• tiktok_ads_get_pixel_list - Liste pixels vinculados à conta do anunciante.
• tiktok_ads_get_pixel_event_stats - Obtenha atividade de eventos de pixel para um intervalo de datas.

Auditoria de Implementação

As ferramentas MCP atuais são listadas apenas quando estão conectadas a OAuth real, estado de token local ou chamadas à API de Marketing do TikTok. Este repositório não expõe ferramentas de espaço reservado ou simuladas.

Ferramenta	Implementação de suporte
tiktok_ads_login	Inicia o OAuth do TikTok e retorna uma URL de autorização.
tiktok_ads_complete_auth	Troca um código OAuth por tokens do TikTok e os armazena localmente.
tiktok_ads_auth_status	Verifica a configuração local e o estado do token salvo.
tiktok_ads_switch_ad_account	Alterna a conta de anunciante local ativa após a autenticação.
tiktok_ads_get_campaigns	Chama a API de Marketing do TikTok campaign/get/.
tiktok_ads_get_campaign_details	Chama a API de Marketing do TikTok campaign/get/ com filtragem campaign_ids.
tiktok_ads_get_adgroups	Chama a API de Marketing do TikTok adgroup/get/.
tiktok_ads_get_adgroup_details	Chama a API de Marketing do TikTok adgroup/get/ com filtragem adgroup_ids.
tiktok_ads_get_ads	Chama a API de Marketing do TikTok ad/get/.
tiktok_ads_get_ad_details	Chama a API de Marketing do TikTok ad/get/ com filtragem ad_ids.
tiktok_ads_get_campaign_performance	Chama a API de Marketing do TikTok report/integrated/get/ em nível de campanha.
tiktok_ads_get_adgroup_performance	Chama a API de Marketing do TikTok report/integrated/get/ em nível de grupo de anúncios.
tiktok_ads_get_ad_performance	Chama a API de Marketing do TikTok report/integrated/get/ em nível de anúncio.
tiktok_ads_get_audience_breakdown	Chama a API de Marketing do TikTok report/integrated/get/ com report_type=AUDIENCE.
tiktok_ads_wasted_spend_audit	Fluxo de trabalho somente leitura que chama campaign/get/, adgroup/get/ e report/integrated/get/.
tiktok_ads_get_custom_audiences	Chama a API de Marketing do TikTok dmp/custom_audience/list/.
tiktok_ads_get_advertiser_info	Chama a API de Marketing do TikTok advertiser/info/ e enriquece com datas de gastos recentes de report/integrated/get/.
tiktok_ads_get_location_info	Chama a API de Marketing do TikTok tool/targeting/info/.
tiktok_ads_get_pixel_list	Chama a API de Marketing do TikTok pixel/list/.
tiktok_ads_get_pixel_event_stats	Chama a API de Marketing do TikTok pixel/event/stats/.

Roteiro

Áreas planejadas:

• Cobertura mais ampla de campanhas GMV Max.
• Operações de escrita seguras para campanhas, grupos de anúncios, anúncios e ativos.
• Gerenciamento de criativos e ativos.
• Ciclo de vida completo de relatórios assíncronos: criar, status e download.
• Descoberta de segmentação e gerenciamento de público.

Solução de Problemas

Falha ao gerar processo: Arquivo ou diretório não encontrado

O cliente MCP não consegue encontrar o comando que você configurou.

Correção:

• Use "command": "uv" se uv estiver no PATH do aplicativo.
• Caso contrário, use o caminho completo, por exemplo:

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

Nenhum módulo chamado 'mcp'

Você está executando o servidor com o Python do sistema em vez do ambiente do projeto.

Corrija sua configuração do MCP para usar:

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

Em seguida, execute:

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

não é possível abrir o arquivo '//run_server.py'

Seu cliente MCP iniciou uv, mas não executou o comando a partir do diretório do projeto.

Corrija sua configuração do MCP para colocar o diretório do projeto nos argumentos uv em vez de depender de cwd:

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

Credenciais da API do TikTok ausentes

O servidor não recebeu TIKTOK_APP_ID ou TIKTOK_APP_SECRET.

Correção:

• Adicione ambos os valores em env na configuração do seu cliente MCP.
• Reinicie seu cliente MCP após alterar a configuração.

OAuth é bem-sucedido, mas as ferramentas ainda dizem não autenticado

Verifique se o arquivo de token existe:

ls ~/.tiktok_ads_mcp/tokens.json

Se você quiser reiniciar a autenticação, remova o arquivo de token e execute tiktok_ads_login novamente:

rm ~/.tiktok_ads_mcp/tokens.json

O Claude Desktop ainda mostra o erro antigo após alterações na configuração

Saia completamente e reabra o Claude Desktop. No macOS, fechar a janela nem sempre é suficiente.

Notas de Segurança

• Não envie .env, arquivos de token, App Secrets ou códigos OAuth.
• Mantenha ~/.tiktok_ads_mcp/tokens.json privado.
• Use um aplicativo de desenvolvedor TikTok com apenas as permissões que você precisa.
• O registro público atual do MCP é somente leitura para objetos do TikTok Ads. Operações de escrita são itens do roteiro e devem ser revisadas cuidadosamente antes de serem expostas.

Desenvolvimento

Instale as dependências:

uv sync

Execute os testes:

uv run --extra dev pytest

Execute o servidor manualmente:

uv run python run_server.py

Licença

Este projeto é licenciado sob a Licença MIT. Consulte LICENSE para detalhes.

Suporte

Para problemas e perguntas, crie um problema neste repositório.