TikTok Ads MCP Server

TikTok Ads MCP Server

Un servidor local de Model Context Protocol (MCP) para la integración con la API de TikTok Ads. Permite que clientes MCP como Claude Desktop se conecten a TikTok Ads, se autentiquen con una app de TikTok Business y usen herramientas de solo lectura para consulta de campañas, inspección de grupos de anuncios y anuncios, informes de rendimiento, desgloses de audiencia, información del anunciante, píxeles y ubicaciones de segmentación.

Qué Hace Este Servidor

• Autenticación: Inicia y completa OAuth de TikTok Ads desde un cliente MCP.
• Consulta de campañas: Lista campañas, inspecciona detalles de campañas, lista grupos de anuncios e inspecciona anuncios.
• Analíticas de rendimiento: Obtén métricas de campañas, grupos de anuncios, anuncios y audiencias para rangos de fechas comunes.
• Datos de audiencia y cuenta: Recupera audiencias personalizadas, información del anunciante, IDs de ubicación, píxeles y estadísticas de eventos de píxel.
• Operación de solo lectura: El registro público de herramientas MCP no expone creación de campañas, creación de grupos de anuncios, carga de creatividades ni otras operaciones de escritura.

Opción Alojada

Este repositorio es para usuarios que quieren ejecutar un servidor MCP local de TikTok Ads.

Si no quieres instalar Python, gestionar dependencias ni configurar una app de desarrollador de TikTok, AdsMCP ofrece un servidor MCP remoto alojado:

Guía de Configuración del Servidor MCP Remoto de AdsMCP

El resto de este README cubre la configuración local.

Requisitos Previos

Necesitas:

• Python 3.10 o superior
• uv para la gestión de dependencias
• Una cuenta de TikTok For Business con acceso a la API de Marketing
• Una app de desarrollador de TikTok con un App ID y un App Secret
• Un cliente MCP que admita servidores stdio locales, como Claude Desktop

Instalar uv

macOS y Linux:

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

Windows PowerShell:

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

Después de la instalación, confirma que uv está disponible:

uv --version

Encuentra la ruta absoluta de uv antes de configurar un cliente MCP de escritorio:

macOS y Linux:

whereis uv
which uv

Usa la ruta devuelta por whereis uv o which uv como valor de command de MCP si tu cliente no puede encontrar uv por nombre.

Windows PowerShell:

where.exe uv

Las rutas comunes son:

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

Instalación Local

Clona el repositorio e instala las dependencias:

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

Encuentra la ruta absoluta del directorio del proyecto. Usarás esta ruta en la configuración MCP como valor de uv --directory:

macOS y Linux:

pwd

Windows PowerShell:

Get-Location

Verifica que el entorno del proyecto puede importar MCP:

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

Deberías ver:

ok

Importante: Usa uv para Ejecutar el Servidor

No configures tu cliente MCP para ejecutar este servidor con el python o python3 del sistema a menos que hayas instalado manualmente todas las dependencias en ese entorno de Python exacto.

Usa esto:

uv run python run_server.py

No esto:

python run_server.py
python3 run_server.py

Por qué: Las aplicaciones de escritorio MCP suelen lanzar un Python diferente al que usas en tu terminal. Si ese Python no tiene instalado el paquete mcp, el servidor se cierra con:

No module named 'mcp'

uv run hace que el cliente MCP use el entorno de dependencias de este proyecto.

Configurar Claude Desktop

Claude Desktop lee su configuración de servidor MCP desde:

macOS:

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

Windows:

%APPDATA%\\Claude\\claude_desktop_config.json

Las rutas de Linux varían según la distribución y el paquete del cliente, pero suelen estar en:

~/.config/Claude/

Configuración de macOS / Linux

Usa uv --directory para que el servidor se inicie desde el directorio del proyecto incluso si tu cliente MCP no aplica cwd correctamente.

Para completar "/absolute/path/to/tiktok-ads-mcp-server", abre una terminal en el repositorio clonado y ejecuta:

pwd

Usa el valor impreso como argumento de --directory. Si Claude no puede encontrar uv, reemplaza "uv" con la ruta absoluta de whereis uv o 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"
      }
    }
  }
}

Configuración de Windows

Usa barras invertidas escapadas en las rutas JSON. Para encontrar la ruta del proyecto, abre PowerShell en el repositorio clonado y ejecuta:

Get-Location

Usa el valor impreso como argumento de --directory, con cada \ escapado como \\ en 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"
      }
    }
  }
}

Si Claude no puede encontrar uv en Windows, usa la ruta completa:

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

Después de editar la configuración, reinicia Claude Desktop por completo.

Configuración de la App de TikTok

1. Ve al TikTok For Business Developer Portal.
2. Crea o abre una app de desarrollador.
3. Copia el App ID y el App Secret.
4. Asegúrate de que la URI de redirección configurada en tu app de TikTok coincida con la URI de redirección que usa este servidor. Por defecto, este proyecto usa:

https://adsmcp.com

5. Añade el App ID y el App Secret a la configuración de tu cliente MCP en env.

Flujo de Autenticación

Una vez que el servidor MCP está conectado:

1. Ejecuta tiktok_ads_login desde tu cliente MCP.
2. Abre la URL de autorización devuelta por la herramienta.
3. Aprueba el acceso en TikTok.
4. Copia el parámetro code de la URL de redirección.
5. Ejecuta tiktok_ads_complete_auth con ese código.
6. Ejecuta tiktok_ads_auth_status para confirmar que la cuenta está autenticada.

Almacenamiento de Tokens y Seguridad

Después de que OAuth se complete, los tokens de acceso y actualización de TikTok se almacenan localmente en:

~/.tiktok_ads_mcp/tokens.json

Este archivo es lo que permite al servidor MCP local llamar a la API de Marketing de TikTok después de autenticarte. Trátalo como una contraseña:

• No lo confirmes en Git ni lo compartas en informes de problemas.
• Mantenlo en tu propia máquina y protégelo con los permisos normales de tu cuenta del sistema operativo.
• Elimínalo si quieres desconectar el servidor local de tu cuenta de TikTok.

El servidor local almacena tokens solo para la cuenta de TikTok que autorizas, y solo para poder realizar llamadas autenticadas a la API de TikTok para esa cuenta.

Herramientas Disponibles

El servidor local expone actualmente las siguientes herramientas a través de su registro MCP. Esta lista es la fuente de verdad para el paquete de código abierto.

Autenticación

• tiktok_ads_login - Inicia la autenticación OAuth de TikTok Ads.
• tiktok_ads_complete_auth - Completa OAuth usando el código de autorización.
• tiktok_ads_auth_status - Comprueba el estado actual de autenticación.
• tiktok_ads_switch_ad_account - Cambia a una cuenta de anunciante diferente.

Gestión de Campañas

• tiktok_ads_get_campaigns - Recupera campañas para la cuenta de anunciante.
• tiktok_ads_get_campaign_details - Obtén detalles de una campaña específica.
• tiktok_ads_get_adgroups - Recupera grupos de anuncios para una campaña.
• tiktok_ads_get_adgroup_details - Obtén detalles de un grupo de anuncios específico.
• tiktok_ads_get_ads - Recupera anuncios por campaña, grupo de anuncios, ID de anuncio o estado.
• tiktok_ads_get_ad_details - Obtén detalles de un anuncio específico.

Rendimiento y Analíticas

• tiktok_ads_get_campaign_performance - Obtén métricas a nivel de campaña.
• tiktok_ads_get_adgroup_performance - Obtén métricas a nivel de grupo de anuncios.
• tiktok_ads_get_ad_performance - Obtén métricas a nivel de anuncio.
• tiktok_ads_get_audience_breakdown - Desglosa el rendimiento de campañas, grupos de anuncios o anuncios por dimensión de audiencia.
• tiktok_ads_wasted_spend_audit - Ejecuta una auditoría de solo lectura para gasto y clics sin señal de conversión.

Creatividad y Audiencia

• tiktok_ads_get_custom_audiences - Lista audiencias personalizadas.
• tiktok_ads_get_advertiser_info - Obtén detalles del anunciante a nivel de cuenta, como moneda, zona horaria, estado, industria, país y fecha de creación.
• tiktok_ads_get_location_info - Resuelve IDs de ubicación de segmentación de TikTok.
• tiktok_ads_get_pixel_list - Lista los píxeles vinculados a la cuenta de anunciante.
• tiktok_ads_get_pixel_event_stats - Obtén la actividad de eventos de píxel para un rango de fechas.

Auditoría de Implementación

Las herramientas MCP actuales solo se listan cuando están conectadas a OAuth real, estado de tokens local o llamadas a la API de Marketing de TikTok. Este repositorio no expone herramientas de marcador de posición ni simuladas.

Herramienta	Implementación subyacente
tiktok_ads_login	Inicia OAuth de TikTok y devuelve una URL de autorización.
tiktok_ads_complete_auth	Intercambia un código OAuth por tokens de TikTok y los almacena localmente.
tiktok_ads_auth_status	Comprueba la configuración local y el estado de tokens guardados.
tiktok_ads_switch_ad_account	Cambia la cuenta de anunciante local activa después de la autenticación.
tiktok_ads_get_campaigns	Llama a la API de Marketing de TikTok campaign/get/.
tiktok_ads_get_campaign_details	Llama a la API de Marketing de TikTok campaign/get/ con filtrado de campaign_ids.
tiktok_ads_get_adgroups	Llama a la API de Marketing de TikTok adgroup/get/.
tiktok_ads_get_adgroup_details	Llama a la API de Marketing de TikTok adgroup/get/ con filtrado de adgroup_ids.
tiktok_ads_get_ads	Llama a la API de Marketing de TikTok ad/get/.
tiktok_ads_get_ad_details	Llama a la API de Marketing de TikTok ad/get/ con filtrado de ad_ids.
tiktok_ads_get_campaign_performance	Llama a la API de Marketing de TikTok report/integrated/get/ a nivel de campaña.
tiktok_ads_get_adgroup_performance	Llama a la API de Marketing de TikTok report/integrated/get/ a nivel de grupo de anuncios.
tiktok_ads_get_ad_performance	Llama a la API de Marketing de TikTok report/integrated/get/ a nivel de anuncio.
tiktok_ads_get_audience_breakdown	Llama a la API de Marketing de TikTok report/integrated/get/ con report_type=AUDIENCE.
tiktok_ads_wasted_spend_audit	Flujo de trabajo de solo lectura que llama a campaign/get/, adgroup/get/ y report/integrated/get/.
tiktok_ads_get_custom_audiences	Llama a la API de Marketing de TikTok dmp/custom_audience/list/.
tiktok_ads_get_advertiser_info	Llama a la API de Marketing de TikTok advertiser/info/ y enriquece con fechas de gasto recientes de report/integrated/get/.
tiktok_ads_get_location_info	Llama a la API de Marketing de TikTok tool/targeting/info/.
tiktok_ads_get_pixel_list	Llama a la API de Marketing de TikTok pixel/list/.
tiktok_ads_get_pixel_event_stats	Llama a la API de Marketing de TikTok pixel/event/stats/.

Hoja de Ruta

Áreas planificadas:

• Mayor cobertura de campañas GMV Max.
• Operaciones de escritura seguras para campañas, grupos de anuncios, anuncios y activos.
• Gestión de creatividades y activos.
• Ciclo de vida completo de informes asíncronos: creación, estado y descarga.
• Descubrimiento de segmentación y gestión de audiencias.

Solución de Problemas

Error al iniciar el proceso: No such file or directory

El cliente MCP no puede encontrar el comando que configuraste.

Solución:

• Usa "command": "uv" si uv está en el PATH de la aplicación.
• De lo contrario, usa la ruta completa, por ejemplo:

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

No module named 'mcp'

Estás ejecutando el servidor con el Python del sistema en lugar del entorno del proyecto.

Corrige tu configuración MCP para usar:

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

Luego ejecuta:

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

can't open file '//run_server.py'

Tu cliente MCP inició uv, pero no ejecutó el comando desde el directorio del proyecto.

Corrige tu configuración MCP para poner el directorio del proyecto en los argumentos de uv en lugar de depender de cwd:

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

Faltan credenciales de la API de TikTok

El servidor no recibió TIKTOK_APP_ID ni TIKTOK_APP_SECRET.

Solución:

• Añade ambos valores en env en la configuración de tu cliente MCP.
• Reinicia tu cliente MCP después de cambiar la configuración.

OAuth se completa, pero las herramientas siguen indicando que no hay autenticación

Comprueba si existe el archivo de token:

ls ~/.tiktok_ads_mcp/tokens.json

Si quieres reiniciar la autenticación, elimina el archivo de token y ejecuta tiktok_ads_login de nuevo:

rm ~/.tiktok_ads_mcp/tokens.json

Claude Desktop sigue mostrando el error anterior después de los cambios de configuración

Cierra y vuelve a abrir Claude Desktop por completo. En macOS, cerrar la ventana no siempre es suficiente.

Notas de Seguridad

• No confirmes .env, archivos de token, App Secrets ni códigos OAuth.
• Mantén ~/.tiktok_ads_mcp/tokens.json privado.
• Usa una app de desarrollador de TikTok solo con los permisos que necesites.
• El registro público actual de MCP es de solo lectura para los objetos de TikTok Ads. Las operaciones de escritura son elementos de la hoja de ruta y deben revisarse cuidadosamente antes de exponerse.

Desarrollo

Instala las dependencias:

uv sync

Ejecuta las pruebas:

uv run --extra dev pytest

Ejecuta el servidor manualmente:

uv run python run_server.py

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta LICENSE para más detalles.

Soporte

Para problemas y preguntas, crea un issue en este repositorio.