TikTok Ads MCP Server

tiktok-ads-mcp-server

Un servidor de Model Context Protocol de código abierto para la API de Negocios de TikTok. Permite que Claude, ChatGPT, Cursor o cualquier cliente MCP lea y analice tus datos publicitarios de TikTok, y los modifique si así lo decides.

Tú lo ejecutas. Tu token permanece en tu máquina. Nada pasa por un intermediario de terceros.

npx -y @getmcpads/tiktok-ads-mcp-server

También está listado en el Registro MCP como com.getmcpads/tiktok-ads, por lo que los clientes que leen el registro pueden instalarlo por nombre.

¿Prefieres no ejecutarlo tú mismo? getmcpads.com es la versión alojada de este servidor, con TikTok Ads junto a Meta Ads, Google Ads, Pinterest Ads, GA4 y Search Console detrás de un único endpoint, OAuth alojado y reportes multiplataforma. Las mismas herramientas, el mismo modelo de seguridad, sin configuración.

---

Lo que obtienes

27 herramientas de lectura	Campañas, grupos de anuncios, anuncios, creatividades, audiencias, píxeles, eventos, Spark Ads, catálogos, diagnósticos de entrega
5 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	Incluyendo las derivadas calculadas en el cliente
16 dimensiones	Con una matriz de compatibilidad que detecta combinaciones inválidas antes de que lleguen 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 hacia adelante	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 por qué. 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 que el modelo verifique 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 de vuelta al modelo, que luego razona sobre datos que nunca se devolvieron. Cada llamada aquí verifica code primero.

---

Cómo se compara con el servidor MCP propio de TikTok

TikTok ofrece un servidor MCP oficial, anunciado en TikTok World '26 y alojado en business-api.tiktok.com/open_mcp/. Es un producto serio, y es más grande que este. Aquí hay una comparación honesta.

	Servidor oficial de TikTok	Este servidor	getmcpads.com
Alojamiento	Alojado por TikTok, remoto	Tú lo alojas. stdio, proceso local	Alojado para ti
Ruta de datos	A través del endpoint de TikTok	Directo a la API de Negocios. Sin intermediario	A través de nuestra pasarela
Herramientas	~400 planas, o ~40 en modo por capas	32 (27 de lectura + 5 de escritura)	32, más 5 otras plataformas
Cobertura	Mucho más amplia	Reportes, estructura, creatividades, audiencias	Igual que este servidor
Escrituras	Aplicadas directamente	Vista previa primero, aplicadas solo con confirm: true	Vista previa primero
Compatibilidad de métricas	Ninguna documentada	El planificador de consultas divide solicitudes incompatibles	Mismo planificador
HTTP 200 en fallos	Manejado internamente	Verificado en cada llamada	Verificado
Auditable	No	Sí. Apache-2.0, lee cada línea	Este servidor, auditado
Modificable	No	Haz un fork	No

Sé claro sobre el equilibrio. Si quieres la superficie más amplia posible de la API de TikTok, el servidor oficial cubre muchos más endpoints que este, y deberías usarlo.

Lo que este servidor ofrece en su lugar es un conjunto curado. TikTok mismo ofrece un modo por capas que expone alrededor de 40 herramientas en lugar de 400, porque cargar cientos de definiciones de herramientas llena el contexto del modelo y hace que elija la herramienta equivocada con más frecuencia. 27 herramientas de lectura bien descritas con un planificador consciente de compatibilidad es una decisión de diseño deliberada, no una brecha.

Elige el servidor oficial para amplitud, o si no necesitas ver el código. Elige este si necesitas que tus datos permanezcan en tu infraestructura, quieres auditar o extender lo que el modelo puede hacer, o quieres escrituras que no puedan dispararse en la primera llamada. Elige getmcpads.com si quieres las capacidades de este servidor sin ejecutarlo, o necesitas más de una plataforma publicitaria en la misma conversación.

---

Obteniendo un token

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

1. Crea una aplicación de desarrollador en el portal de desarrolladores de TikTok for Business.
2. Anota el ID de App y el Secreto de App desde la página de la aplicación.
3. Autoriza las cuentas de anunciante que quieras alcanzar. 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 en un horario 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 la API para Negocios de TikTok

Ejecuta tiktok_health_check como tu 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 reportes 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 el código 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 aplicación
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 a 1 para registrar las 5 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 desactivadas por defecto. Actívalas con TIKTOK_ENABLE_WRITES=1.

Cuando están activadas, 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 que el error sea visible 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

27 herramientas de lectura

Descubrimiento y salud

Herramienta	Propósito
tiktok_health_check	Verifica credenciales y acceso de anunciante sin exponer el token
tiktok_list_advertisers	Cada cuenta de anunciante a la que el token puede acceder
tiktok_get_advertiser_info	Metadatos de cuenta: nombre, moneda, zona horaria, estado

Estructura

Herramienta	Propósito
tiktok_get_campaigns / tiktok_get_adgroups / tiktok_get_ads	Lista entidades y sus configuraciones
tiktok_get_delivery_status	Estado de entrega y por qué podría estar limitada

Rendimiento

Herramienta	Propósito
tiktok_get_insights	La herramienta principal de reportes. Métricas, dimensiones, planificación consciente de compatibilidad
tiktok_validate_query	Verifica una combinación de métrica y dimensión antes de ejecutarla
tiktok_get_report_raw	Campos de reporte nativos, sin alias
tiktok_get_async_report_status	Rastrea un reporte asíncrono de larga duración

Creatividades

Herramienta	Propósito
tiktok_get_creatives	Texto de creatividad de anuncio, IDs de medios, URLs de destino
tiktok_get_video_assets	Activos de video y sus metadatos
tiktok_get_creative_fatigue_recipes	Flujos de trabajo para detectar fatiga creativa
tiktok_get_spark_ads / tiktok_get_spark_organic_joins	Spark Ads y sus contrapartes orgánicas

Audiencias y segmentación

Herramienta	Propósito
tiktok_get_audiences / tiktok_get_audience_details	Audiencias personalizadas y similares
tiktok_get_audience_overlap	Superposición entre audiencias
tiktok_get_targeting_catalog	Opciones de segmentación disponibles

Search Ads

Herramienta	Propósito
tiktok_search_keywords	Sugerencias de palabras clave para TikTok Search Ads
tiktok_get_search_ads_maturity	Qué tan lista está una cuenta para Search Ads

Comercio y señales

Herramienta	Propósito
tiktok_get_pixels / tiktok_get_events	Píxeles y los eventos que reciben
tiktok_get_shop_catalog_diagnostics	Salud del catálogo y del feed de productos

Vías de escape

Herramienta	Propósito
tiktok_get_read_endpoint	Llama directamente a un endpoint de lectura en lista blanca
tiktok_get_entities_raw	Lecturas de entidades en bruto con tu propia selección de campos

Estas existen para que un nuevo campo de API no requiera una nueva versión. Los endpoints de mutación, los endpoints OAuth y los parámetros de credenciales están bloqueados en estas rutas, por lo que un argumento manipulado no puede convertir una herramienta de lectura en una de escritura.

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 tiene 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 se rechaza en lugar de llamarse. Cubierto por pruebas.
• Se rechazan las redirecciones una vez que se adjunta un token, por lo que una redirección no puede reenviar tu credencial a otro lugar.
• Los endpoints de mutación y OAuth están bloqueados en las rutas de lectura genéricas. Cubierto por pruebas.
• Sin telemetría. El servidor no hace ninguna llamada de red aparte de la API de Negocios de TikTok. Puedes verificar esto buscando fetch en el código fuente.

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

---

¿Buscas una versión gestionada y multiplataforma?

Este servidor hace una plataforma, en tu máquina, con tu token. Eso es a propósito.

Si prefieres no ejecutarlo tú mismo, o necesitas TikTok Ads junto con Meta Ads, Google Ads, Pinterest Ads, GA4 y Search Console detrás de un solo endpoint, con OAuth alojado y reportes multiplataforma, eso es lo que construimos en getmcpads.com.

Misma filosofía, menos infraestructura. Este proyecto permanece de código abierto e independientemente útil de cualquier manera.

---

Contribuciones

Los issues y las pull requests son bienvenidos. Consulta CONTRIBUTING.md. Lee SECURITY.md antes de reportar cualquier problema relacionado con la seguridad.

Licencia

Licencia Apache 2.0. Consulta 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.