TikTok Ads MCP Server

El vídeo demuestra getmcpads alojado con datos simulados. Sus galerías creativas y la interfaz de MCP Apps pertenecen al producto alojado. Este repositorio proporciona las herramientas independientes de la API nativa.

35 herramientas de lectura · 29 herramientas de escritura, deshabilitadas por defecto.

Ejecútalo localmente con tus propias credenciales de la plataforma y un cliente compatible con stdio MCP, como Claude Desktop, Claude Code o Cursor. Tus solicitudes van directamente a la plataforma. Para conexiones gestionadas, incluidas las configuraciones compatibles con ChatGPT, usa la opción alojada.

Novedades

v2.0.0: Herramientas nativas y actualización de seguridad · 20 de septiembre de 2026

• Conserva los IDs de 64 bits sin comillas exactos en las respuestas de lectura, escritura y verificación.
• Corrige la selección de campos de campaña y los límites de lista predeterminados.
• Actualiza la validación nativa de escritura para presupuestos, programaciones, segmentación y relectura. Añade herramientas de música para carrusel, disponibilidad de vídeo subido, portafolio de CTA e identidad personalizada.
• Requiere Node.js 22.12 o superior y verifica Node 22/24 en CI.
• Actualiza dependencias vulnerables y regenera el catálogo MCP.

Registro de cambios completo · Detalles de sincronización de fuentes · Todas las versiones

Notas de actualización

Requiere Node.js 22.12 o superior. CI cubre Node 22 y 24. La versión 2.0.0 elimina el soporte para Node 18 y 20. Lee los esquemas de herramientas actuales antes de reutilizar argumentos guardados. Las escrituras siguen siendo opcionales y requieren confirmación explícita. Las integraciones creativas alojadas y la interfaz de MCP Apps quedan fuera de esta versión.

Instalar esta versión

Esta es una versión de fuente de GitHub. Las versiones de npm y del Registro MCP se publican por separado. Los comandos siguientes seleccionan esta versión exacta; los ejemplos de npx sin fijar más adelante en este documento seleccionan la versión actualmente disponible en 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

Configura tu cliente MCP para ejecutar node con la ruta absoluta a dist/cli.js y las credenciales de la plataforma documentadas abajo.

¿Prefieres una conexión gestionada? Usa TikTok Ads con getmcpads alojado. Conecta tu cuenta, selecciona los datos a los que tu asistente puede acceder y usa la conexión MCP alojada. Consulta el sitio para conocer las funciones y planes actuales.

Qué incluye

35 herramientas de lectura	Campañas, grupos de anuncios, anuncios, creatividades, audiencias, píxeles, eventos, Spark Ads, catálogos, diagnóstico de entrega
29 herramientas de escritura	Desactivadas por defecto. Estado de campañas y grupos de anuncios, presupuestos, creación de campañas. Cada una muestra una vista previa antes de aplicarse
277 métricas	Incluidas las derivadas calculadas en el cliente
16 dimensiones	Con una matriz de compatibilidad que detecta combinaciones inválidas antes de llegar a la API
5 recursos	Catálogos en vivo que el modelo puede leer: métricas, dimensiones, reglas de compatibilidad, 12 recetas de flujos de trabajo
Investigación de palabras clave	tiktok_search_keywords y tiktok_get_search_ads_maturity, para TikTok Search Ads
Lecturas compatibles con el futuro	tiktok_get_read_endpoint, tiktok_get_entities_raw, tiktok_get_report_raw alcanzan endpoints que este servidor aún no modela

El planificador de consultas

TikTok rechaza muchas combinaciones de métricas y dimensiones, y sus mensajes de error rara vez explican el motivo. Este servidor codifica la matriz de compatibilidad, por lo que divide una solicitud imposible en varias llamadas válidas a la API y fusiona los resultados en lugar de fallar.

tiktok_validate_query permite al modelo comprobar una combinación antes de gastar una llamada en ella.

Una trampa que este servidor maneja por ti

TikTok responde con HTTP 200 incluso cuando la llamada falló. El campo aplicativo code es lo que decide. Un cliente que confía en el estado HTTP reporta éxitos imaginarios al modelo, que luego razona sobre datos que nunca se devolvieron. Cada llamada aquí verifica code primero.

---

Obtener un token

TikTok necesita dos valores, no uno: un token de acceso y el ID de App al que pertenece.

1. Crea una app de desarrollador en el portal para desarrolladores de TikTok for Business.
2. Anota el ID de App y el Secreto de App desde la página de la app.
3. Autoriza las cuentas de anunciante a las que quieras acceder. TikTok otorga acceso por anunciante, por lo que una cuenta que omitas aquí permanecerá invisible para el servidor sin importar lo que permita el token.
4. Completa el flujo de autorización OAuth para intercambiar el auth_code devuelto por un token de acceso. Los tokens de larga duración de TikTok no expiran según un calendario fijo, pero se revocan cuando se retira la autorización.
5. Coloca el token en TIKTOK_ACCESS_TOKEN y el ID de App en TIKTOK_APP_ID.

📖 Documentación de TikTok API for Business

Ejecuta tiktok_health_check como primera llamada. Verifica las credenciales, lista las cuentas de anunciante a las que realmente puedes acceder e informa qué falta, sin imprimir tu token.

¿Qué permisos?

Grupo de alcances	Cuándo lo necesitas
Alcances de informes y lectura	Siempre. Campañas, grupos de anuncios, anuncios, insights
Alcances de gestión de campañas	Solo si configuras TIKTOK_ENABLE_WRITES=1
Alcances de Catálogo y Business Center	Opcional, para tiktok_get_shop_catalog_diagnostics

---

Configuración

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %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"
      }
    }
  }
}

Reinicia Claude Desktop. Pregúntale: "lista mis cuentas de anunciante de 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 en tu proyecto, con la misma forma que la configuración de Claude Desktop anterior.

Desde la fuente

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

Configuración

Variable	Predeterminado	Significado
TIKTOK_ACCESS_TOKEN	ninguno	Requerido. Tu token de acceso
TIKTOK_APP_ID	ninguno	Requerido. El ID de App al que pertenece el token
TIKTOK_APP_SECRET	ninguno	Opcional, para endpoints que requieren autenticación de app
TIKTOK_ADVERTISER_ID	ninguno	Predeterminado opcional, evita pasarlo en cada llamada
TIKTOK_BC_ID	ninguno	ID de Business Center opcional
TIKTOK_ENABLE_WRITES	sin configurar	Configúralo en 1 para registrar las 29 herramientas de escritura
LOG_LEVEL	info	debug, info, warn, error

Verifica tu configuración en cualquier momento:

npm run doctor

---

Escrituras, y por qué muestran vista previa primero

Las herramientas de escritura están deshabilitadas por defecto. Actívalas con TIKTOK_ENABLE_WRITES=1.

Cuando están habilitadas, cada herramienta de escritura devuelve una vista previa y no cambia 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."
}

Solo una segunda llamada que lleve confirm: true toca la cuenta en vivo.

Esto es deliberado. Un asistente compone estas llamadas y puede elegir el anunciante equivocado, la campaña equivocada o el orden de magnitud equivocado en un presupuesto. Una vista previa obligatoria hace visible el error antes de que cueste dinero y le da a un humano el punto de detención que el protocolo no garantiza por sí solo.

Una salvaguarda adicional: tiktok_create_campaign siempre crea la campaña DISABLE. No hay opción para crearla en ejecución.

Herramienta	Qué cambia
tiktok_update_campaign_status / tiktok_update_adgroup_status	Pausar o reactivar
tiktok_update_campaign_budget / tiktok_update_adgroup_budget	Presupuesto, en la moneda de la cuenta
tiktok_create_campaign	Crea una campaña, siempre DISABLE

---

Herramientas

Cada herramienta se lista a continuación. Consulta server-card.json para los esquemas completos de parámetros y salidas.

35 herramientas de lectura

| Herramienta | Propósito | | --- | --- | | `tiktok_health_check` | Verificación de salud de solo lectura para las credenciales de TikTok, anunciantes accesibles e información del anunciante. | | `tiktok_list_advertisers` | Listar todas las cuentas de anunciantes de TikTok accesibles con el token actual. | | `tiktok_get_advertiser_info` | Obtener información detallada para cuentas específicas de anunciantes de TikTok: moneda, zona horaria, estado, saldo. | | `tiktok_get_campaigns` | Listar campañas para una cuenta de anunciante de TikTok. | | `tiktok_get_adgroups` | Leer la configuración completa del grupo de anuncios nativo, incluyendo segmentación, referencias de audiencias personalizadas/similares y exclusiones, geografía, idioma, edad/género, ubicaciones, intereses/comportamientos, presupuesto y programación. | | `tiktok_get_targeting` | Leer la segmentación configurada del grupo de anuncios y las referencias de audiencia: inclusiones/exclusiones personalizadas/similares, geografía, idioma, edad/género, ubicaciones, intereses y comportamientos. | | `tiktok_get_audience_report` | Leer informes de rendimiento de AUDIENCIA de TikTok por edad o género a nivel de anunciante, campaña, grupo de anuncios o anuncio, incluyendo la entrega de campañas Smart+ elegibles. | | `tiktok_get_ads` | Listar anuncios para un anunciante de TikTok. | | `tiktok_get_insights` | Consultar información de rendimiento de anuncios de TikTok utilizando el catálogo de métricas nativas/calculadas actual y la planificación de consultas. | | `tiktok_get_creatives` | Obtener detalles creativos (video, imagen, texto) para anuncios específicos en una cuenta de anunciante de TikTok. | | `tiktok_get_audiences` | Listar audiencias personalizadas y similares para una cuenta de anunciante de TikTok. | | `tiktok_search_keywords` | Obtener sugerencias de palabras clave para TikTok Search Ads. | | `tiktok_validate_query` | Validar una combinación de métrica/dimensión de TikTok ANTES de ejecutar. | | `tiktok_get_pixels` | Listar píxeles de TikTok y, cuando los permisos lo permitan, metadatos de eventos de píxel para un anunciante. | | `tiktok_get_events` | Descubrir eventos de píxel/aplicación o diagnósticos de seguimiento accesibles para un anunciante. | | `tiktok_get_delivery_status` | Agregar estado de entrega de campaña, grupo de anuncios y anuncio/estado de operación con diagnósticos simples. | | `tiktok_get_async_report_status` | Verificar el estado de una tarea de informe asíncrono de TikTok por taskId cuando los endpoints de informe asíncrono estén disponibles. | | `tiktok_get_video_assets` | Devolver metadatos de activos de video de TikTok vinculados a anuncios desde ad/get y endpoints de material de video cuando estén disponibles. | | `tiktok_get_spark_ads` | Devolver contexto de Spark Ads desde campos de anuncios cuando esté disponible, con un respaldo conservador si los campos específicos de Spark no son compatibles. | | `tiktok_get_audience_details` | Obtener detalles de audiencias personalizadas/similares/guardadas donde los endpoints DMP de TikTok sean accesibles. | | `tiktok_get_shop_catalog_diagnostics` | Diagnósticos de solo lectura de TikTok Shop/catálogo/comercio electrónico. | | `tiktok_get_search_ads_maturity` | Diagnosticar la madurez de TikTok Search Ads a partir de informes de palabras clave/búsqueda y endpoints opcionales de recomendación de palabras clave. | | `tiktok_get_creative_fatigue_recipes` | Encontrar patrones probables de fatiga creativa a partir de informes diarios a nivel de anuncio y devolver recetas de renovación de solo lectura. | | `tiktok_get_audience_overlap` | Diagnósticos de superposición de audiencias de solo lectura entre grupos de anuncios, audiencias personalizadas, audiencias guardadas y campos de segmentación. | | `tiktok_get_spark_organic_joins` | Unir campos de Spark Ads accesibles con informes de páginas/publicaciones pagadas y endpoints opcionales de identidad/publicaciones orgánicas cuando los permisos lo permitan. | | `tiktok_list_ad_videos` | Listar toda la biblioteca de videos del anunciante (archivo/video/anuncio/búsqueda): nombre de archivo, duración, dimensiones, firma y URL de vista previa y portada servidas públicamente. | | `tiktok_list_ad_images` | Listar toda la biblioteca de imágenes del anunciante (archivo/imagen/anuncio/búsqueda): nombre de archivo, dimensiones, firma, usabilidad en carrusel y una URL de imagen servida públicamente firmada por aproximadamente treinta días (image_url_expires_at da el instante exacto). | | `tiktok_get_asset_urls` | Re-resolver URLs frescas y públicamente obtenibles para activos específicos de la biblioteca de TikTok (archivo/video/anuncio/info y archivo/imagen/anuncio/info). | | `tiktok_get_entities_raw` | Listar campañas, grupos de anuncios o anuncios de TikTok con campos nativos seleccionados por el llamador, filtrado, ordenamiento y paginación. | | `tiktok_get_report_raw` | Ejecutar un informe síncrono nativo BASIC o AUDIENCE de TikTok con dimensiones y métricas seleccionadas por el llamador. | | `tiktok_get_targeting_catalog` | Leer catálogos de segmentación y planificación de TikTok: ubicaciones, idiomas, intereses, comportamientos, hashtags, ideas/salud de palabras clave de Search Ads, dispositivos, operadores, etiquetas contextuales, exclusiones de contenido y zonas horarias. | | `tiktok_get_read_endpoint` | Vía de escape avanzada de solo GET de la API de Negocios de TikTok para endpoints JSON de lectura documentados aún no modelados por una herramienta MCP especializada. | | `tiktok_get_carousel_music` | Obtener recomendaciones de música de TikTok para exactamente las imágenes subidas en un anuncio de imagen estándar no catálogo (una tarjeta) o carrusel. | | `tiktok_get_uploaded_video` | Leer un video subido de la biblioteca de medios de este anunciante. | | `tiktok_get_write_context` | Leer la entidad exacta de TikTok, la configuración del padre y la moneda/zona horaria del anunciante antes de editar o construir una nueva configuración. |

29 herramientas de escritura

Deshabilitadas por defecto. Las llamadas son de vista previa a menos que se confirmen explícitamente. Verifique la configuración y el esquema exacto antes de usar.

Herramienta	Propósito
tiktok_create_cta_portfolio	Crear un portafolio de CTA dinámico a partir de las recomendaciones aprobadas exactas devueltas por creative/cta/recommend para este anunciante.
tiktok_create_custom_identity	Crear una identidad publicitaria CUSTOMIZED_USER propiedad del anunciante para Pangle o Global App Bundle.
tiktok_create_campaign_advanced	Crear campaña clásica de TikTok DISABLED.
tiktok_update_campaign_configuration	Actualizar campaña clásica de TikTok.
tiktok_create_adgroup	Crear grupo de anuncios clásico de TikTok DISABLED.
tiktok_update_adgroup_configuration	Actualizar grupo de anuncios clásico de TikTok.
tiktok_create_ads	Crear anuncios clásicos de TikTok DISABLED (video, imagen, carrusel o contenido Spark autorizado).
tiktok_update_ads	Actualizar anuncios clásicos de TikTok (video, imagen, carrusel o contenido Spark autorizado).
tiktok_create_smart_plus_campaign	Crear campaña de TikTok Smart+ mejorada DISABLED.
tiktok_update_smart_plus_campaign	Actualizar campaña de TikTok Smart+ mejorada.
tiktok_create_smart_plus_adgroup	Crear grupo de anuncios de TikTok Smart+ mejorado DISABLED.
tiktok_update_smart_plus_adgroup	Actualizar grupo de anuncios de TikTok Smart+ mejorado.
tiktok_create_smart_plus_ad	Crear anuncios de TikTok Smart+ mejorados DISABLED (video, imagen, carrusel o contenido Spark autorizado).
tiktok_update_smart_plus_ad	Actualizar anuncios de TikTok Smart+ mejorados (video, imagen, carrusel o contenido Spark autorizado).
tiktok_update_ad_status	Pausar o reactivar exactamente un anuncio clásico.
tiktok_update_smart_plus_campaign_status	Pausar o reactivar exactamente una campaña Smart+.
tiktok_update_smart_plus_adgroup_status	Pausar o reactivar exactamente un grupo de anuncios Smart+.
tiktok_update_smart_plus_ad_status	Pausar o reactivar exactamente un anuncio Smart+.
tiktok_update_smart_plus_material_status	Pausar o reactivar materiales creativos seleccionados dentro de un anuncio Smart+ mejorado.
tiktok_rename_campaign	Renombrar una campaña clásica de TikTok.
tiktok_rename_adgroup	Renombrar un grupo de anuncios clásico de TikTok.
tiktok_rename_ad	Renombrar un anuncio clásico de TikTok.
tiktok_upload_ad_image	Importar una imagen desde una URL de medios HTTPS pública o archivo base64 (hasta 5 MiB).
tiktok_upload_ad_video	Importar un video desde una URL de medios HTTPS pública o archivo base64 (hasta 5 MiB).
tiktok_update_campaign_status	Pausar o reactivar una campaña de TikTok.
tiktok_create_campaign	Crear una campaña de TikTok.
tiktok_update_campaign_budget	Cambiar el presupuesto de una campaña de TikTok, en la moneda de la cuenta.
tiktok_update_adgroup_status	Pausar o reactivar un grupo de anuncios de TikTok.
tiktok_update_adgroup_budget	Cambiar el presupuesto de un grupo de anuncios de TikTok.

5 recursos

URI	Contenido
tiktok://manifest	Lo que expone este servidor y su modo actual
tiktok://metrics	Las 277 métricas con categorías y formatos
tiktok://dimensions	Las 16 dimensiones y dónde son válidas
tiktok://compatibility	La matriz de compatibilidad
tiktok://recipes	12 flujos de trabajo paso a paso

---

Seguridad

El servidor contiene una credencial que puede leer y, opcionalmente, modificar cuentas publicitarias en vivo. Concretamente:

• El token nunca se registra. La salida de depuración imprime Access-Token: [redacted].
• Las solicitudes van solo a business-api.tiktok.com, y solo bajo /open_api/v1.3/. Cualquier otro host o ruta es rechazado en lugar de ser llamado. Cubierto por pruebas.
• Las redirecciones son rechazadas una vez que se adjunta un token, por lo que una redirección no puede reenviar su credencial a otro lugar.
• Los endpoints de mutación y OAuth están bloqueados en las rutas genéricas de lectura. Cubierto por pruebas.
• Sin telemetría. El servidor no realiza ninguna llamada de red aparte de la API de Negocios de TikTok. Puede verificar esto buscando en el código fuente fetch.

Política completa e instrucciones de reporte: SECURITY.md.

---

¿Buscando una versión gestionada y multiplataforma?

Pruebe TikTok Ads alojado si desea usar esta fuente sin operar un servidor local. getmcpads también conecta publicidad, Search Console y GA4 a través de una única URL MCP. La disponibilidad de la fuente y los límites del plan se enumeran en el sitio; aún se requiere conectar una cuenta.

1. Siga la guía de conexión de TikTok Ads.
2. Seleccione la cuenta o propiedad que su asistente puede leer.
3. Conecte Claude, ChatGPT o Codex.
4. Pruebe una revisión de solo lectura: "Compare tendencias de entrega y conversión de campañas en períodos completos. Indique datos faltantes y no cambie nada."

Vea el catálogo actual de herramientas alojadas y precios antes de elegir un plan de pago. Este adaptador Apache 2.0 sigue siendo útil de forma independiente con sus propias credenciales.

---

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas. Consulte CONTRIBUTING.md. Por favor, lea SECURITY.md antes de reportar cualquier cosa relacionada con seguridad.

Licencia

Licencia Apache 2.0. Consulte también NOTICE.

TikTok y TikTok for Business son marcas comerciales de ByteDance Ltd. y sus afiliados. Este proyecto no está afiliado, respaldado ni patrocinado por TikTok o ByteDance. Es un cliente independiente de una API pública.

Contratos MCP y paquete de escritorio

Cada herramienta declara anotaciones de lectura/escritura, descripciones de parámetros y un esquema de salida estructurado. Las llamadas exitosas exponen la carga útil como structuredContent.result; los errores conservan isError: true. La tarjeta de servidor generada contiene solo definiciones.

Ejecute npm run bundle -- /path/to/output para construir un paquete de escritorio .mcpb a partir del catálogo actual. Las credenciales se ingresan localmente durante la instalación. Las herramientas de escritura permanecen deshabilitadas a menos que se habiliten explícitamente.

Más de getmcpads

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

Mantenido por Emmanuel en getmcpads. Preguntas: hello@getmcpads.com.