Google Tag Manager

Servidor MCP para Google Tag Manager

Una interfaz para la API de Google Tag Manager a través de MCP, en dos variantes: un servidor alojado con Google OAuth integrado, y una CLI local que se ejecuta con tus propias credenciales.

Tabla de contenidos

• Servidor MCP para Google Tag Manager
  • Tabla de contenidos
  • Estructura del repositorio
  • Instalación
    • Claude Desktop
    • Claude Code
    • VS Code
    • GitHub Copilot
    • Copilot CLI
    • Cursor
    • Antigravity
    • ChatGPT
    • Otros clientes MCP
    • Solución de problemas
  • Prueba tus cambios localmente
    • Cambios en packages/core o packages/cli
    • Cambios en apps/worker
      • 1. Configura un cliente OAuth de Google Cloud
      • 2. Configura las variables de entorno locales
      • 3. Inicia el servidor
      • 4. Apunta tu cliente MCP al servidor local
  • Publicación de versiones
  • Desarrollo
  • Recursos útiles
  • Código abierto

Estructura del repositorio

Espacio de trabajo npm con una aplicación y dos paquetes publicados:

Las herramientas llegan a Google a través de un GtmAuthProvider (getAccessToken(): Promise<string>) en lugar de a través de una sesión particular, lo que permite que el mismo conjunto de herramientas respalde ambos servidores — y uno privado con tu propia autenticación. Consulta el README del paquete principal.

Instalación

Este servidor viene en dos variantes: servidor alojado y CLI local. Ambos te ofrecen las mismas 18 herramientas de GTM; la diferencia es quién maneja la autenticación de Google.

Si eres un colaborador que prueba un cambio no publicado en lugar de simplemente usar las herramientas, omite todo lo siguiente y consulta Prueba tus cambios localmente.

Elige tu cliente a continuación. El servidor alojado necesita el puente mcp-remote en clientes cuyo soporte MCP no complete el flujo OAuth de Google de forma nativa; donde un cliente lo hace por sí mismo, se conecta directamente a https://gtm-mcp.stape.ai/mcp.

Claude Desktop

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

Claude Code

claude mcp add --transport http gtm-mcp-server https://gtm-mcp.stape.ai/mcp

claude mcp add gtm-mcp-server -e GOOGLE_SERVICE_ACCOUNT_KEY='{"type":"service_account", ... }' -- npx -y google-tag-manager-mcp-server

VS Code

{
  "servers": {
    "gtm-mcp-server": {
      "type": "http",
      "url": "https://gtm-mcp.stape.ai/mcp"
    }
  }
}

{
  "servers": {
    "gtm-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

GitHub Copilot

Copilot CLI

{
  "mcpServers": {
    "gtm-mcp-server": {
      "type": "http",
      "url": "https://gtm-mcp.stape.ai/mcp"
    }
  }
}

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "gtm-mcp-server": {
      "url": "https://gtm-mcp.stape.ai/mcp"
    }
  }
}

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

Antigravity

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gtm-mcp.stape.ai/mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

ChatGPT

Otros clientes MCP

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gtm-mcp.stape.ai/mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

Solución de problemas

Límite de longitud del nombre del servidor MCP

Algunos clientes MCP (como Cursor AI) tienen un límite de 60 caracteres para la longitud combinada del nombre del servidor MCP + nombre de la herramienta. Si usas un nombre de servidor más largo en tu configuración (por ejemplo, gtm-mcp-server-your-additional-long-name), algunas herramientas pueden filtrarse.

Para evitar este problema:

• Usa nombres de servidor más cortos en tu configuración MCP (por ejemplo, gtm-mcp-server)

Borrado de la caché MCP

Si te conectas a través de mcp-remote (Antigravity, o Claude Desktop configurado de esa manera), almacena toda la información de credenciales dentro de ~/.mcp-auth (o donde apunte tu MCP_REMOTE_CONFIG_DIR). Si tienes problemas persistentes, intenta ejecutar:

rm -rf ~/.mcp-auth

Luego, reinicia tu cliente MCP.

Prueba tus cambios localmente

Qué flujo de trabajo necesitas depende de lo que hayas cambiado. La mayoría de los cambios están en la primera categoría — recurre a la segunda solo si estás tocando el propio Worker.

Cambios en packages/core o packages/cli

Esta es la lógica de las herramientas en sí (esquemas, llamadas a la API de GTM, manejo de errores) — casi todo lo que corregirías o añadirías vive aquí. No necesitas un cliente OAuth de Google Cloud ni configuración de Worker: compila desde el código fuente y ejecuta la CLI directamente con credenciales que ya tengas.

git clone https://github.com/stape-io/google-tag-manager-mcp-server
cd google-tag-manager-mcp-server
gh pr checkout <PR number>   # or: git checkout <your-branch>
npm install
npm run build

Apunta tu cliente MCP a la compilación local en lugar de npx — mismas opciones de credenciales que el ejemplo de CLI local de Claude Desktop arriba, un token de acceso del OAuth Playground es la forma más rápida de probar un solo cambio:

{
  "mcpServers": {
    "gtm-mcp-local": {
      "command": "node",
      "args": ["/absolute/path/to/google-tag-manager-mcp-server/packages/cli/dist/index.js"],
      "env": {
        "GOOGLE_ACCESS_TOKEN": "..."
      }
    }
  }
}

Consulta el README de la CLI para conocer todas las opciones de credenciales.

Cambios en apps/worker

Solo se necesita para el código propio del servidor alojado: el flujo OAuth, el enrutamiento, el manejo de sesiones, las páginas de aprobación y estado. Esto ejecuta ese código en tu propia máquina contra tus propias credenciales OAuth de Google Cloud en lugar de gtm-mcp.stape.ai.

1. Configura un cliente OAuth de Google Cloud

1. En la Google Cloud Console, crea o selecciona un proyecto, luego habilita la API de Tag Manager.
2. Ve a APIs y servicios > Pantalla de consentimiento de OAuth y configúrala (Externa está bien). Mientras la aplicación esté en estado de publicación Prueba, solo las cuentas listadas como usuarios de prueba pueden iniciar sesión.
3. Ve a Audiencia, bajo Usuarios de prueba añade tu propia cuenta de Google.
4. Ve a APIs y servicios > Credenciales > Crear credenciales > ID de cliente de OAuth, tipo Aplicación web.
5. Bajo URIs de redireccionamiento autorizados, añade http://localhost:8788/callback. (Puedes dejar Orígenes de JavaScript autorizados vacío — este flujo es solo del lado del servidor, ningún JS del navegador llama a Google directamente.)
6. Guarda, luego copia el ID de cliente y el Secreto de cliente generados.

2. Configura las variables de entorno locales

Copia el archivo de ejemplo y completa los valores del paso anterior:

cp apps/worker/.dev.vars.example apps/worker/.dev.vars

GOOGLE_CLIENT_ID="<your client ID>"
GOOGLE_CLIENT_SECRET="<your client secret>"
COOKIE_ENCRYPTION_KEY="<any random string, at least 32 chars, e.g. output of: openssl rand -hex 32>"
WORKER_HOST="http://localhost:8788"
HOSTED_DOMAIN=""

.dev.vars está en git-ignore — solo se usa localmente y nunca se confirma.

3. Inicia el servidor

npm install
npm run build
npm run dev

npm run build compila el paquete principal contra el que se agrupa el Worker; npm run dev inicia el Worker en http://localhost:8788.

4. Apunta tu cliente MCP al servidor local

Los conectores personalizados de Claude Desktop necesitan una URL accesible públicamente, por lo que mcp-remote es la única opción para apuntar a localhost:

{
  "mcpServers": {
    "gtm-mcp-server-local": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8788/mcp"]
    }
  }
}

Reinicia Claude Desktop. Se abrirá una ventana del navegador para el flujo OAuth de Google; inicia sesión con la cuenta que añadiste como usuario de prueba en el paso 1.

Nota: si te has conectado previamente al servidor alojado (o alternas entre local y alojado), borra primero la caché de mcp-remote (consulta Solución de problemas arriba) y reinicia completamente tu cliente MCP, de lo contrario podría reutilizar una conexión obsoleta/en caché.

Publicación de versiones

Las versiones y los registros de cambios se gestionan con Changesets. Junto con un cambio que deba publicarse, añade:

npm run changeset

Al fusionar en main el flujo de trabajo de publicación abre un PR de "Version Packages"; fusionar ese PR publica en npm, primero el paquete principal y luego la CLI que depende de él. El Worker es privado y nunca se publica — se despliega desde main en cada push.

Desarrollo

npm install
npm run build      # core, then the CLI, then the Worker's generated version
npm run typecheck
npm run lint
npm run smoke      # starts the built CLI and runs an MCP handshake against it

Las solicitudes de extracción ejecutan todo lo anterior más una verificación del paquete del Worker, y marcan cambios en un paquete publicado que lleguen sin un changeset. Tanto @modelcontextprotocol/sdk como agents están fijados a versiones exactas en apps/worker. El SDK identifica los esquemas de herramientas con instanceof, por lo que todo el espacio de trabajo debe resolver una única copia, y las versiones de agents fijan la versión del SDK contra la que fueron compiladas. Actualízalos juntos y despliega con cuidado.

Recursos útiles

• Guía paso a paso: Servidor MCP para Google Tag Manager

Código abierto

El Servidor MCP para Google Tag Manager es desarrollado y mantenido por Stape Team bajo la licencia Apache 2.0.