Google Tag Manager

Servidor MCP para Google Tag Manager

Uma interface para a API do Google Tag Manager via MCP, em duas versões: um servidor hospedado com OAuth do Google integrado e uma CLI local que roda com suas próprias credenciais.

Sumário

• Servidor MCP para Google Tag Manager
  • Sumário
  • Estrutura do repositório
  • Instalação
    • Claude Desktop
    • Claude Code
    • VS Code
    • GitHub Copilot
    • Copilot CLI
    • Cursor
    • Antigravity
    • ChatGPT
    • Outros clientes MCP
    • Solução de problemas
  • Teste suas alterações localmente
    • Alterações em packages/core ou packages/cli
    • Alterações em apps/worker
      • 1. Configure um cliente OAuth do Google Cloud
      • 2. Configure as variáveis de ambiente locais
      • 3. Inicie o servidor
      • 4. Aponte seu cliente MCP para o servidor local
  • Publicação
  • Desenvolvimento
  • Recursos úteis
  • Código aberto

Estrutura do repositório

Workspace npm com um aplicativo e dois pacotes publicados:

As ferramentas acessam o Google por meio de um GtmAuthProvider (getAccessToken(): Promise<string>) em vez de qualquer sessão específica, o que permite que o mesmo conjunto de ferramentas alimente ambos os servidores — e um privado com sua própria autenticação. Consulte o README do pacote principal.

Instalação

Este servidor vem em duas versões: Servidor hospedado e CLI local. Ambos oferecem as mesmas 18 ferramentas do GTM; a diferença é quem lida com a autenticação do Google.

Se você é um colaborador testando uma alteração não publicada em vez de apenas usar as ferramentas, ignore tudo abaixo e consulte Teste suas alterações localmente.

Escolha seu cliente abaixo. O servidor hospedado precisa da ponte mcp-remote em clientes cujo suporte a MCP não conclui o fluxo OAuth do Google nativamente; onde um cliente faz isso sozinho, ele se conecta diretamente 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

Outros 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\", ... }"
      }
    }
  }
}

Solução de problemas

Limite de comprimento do nome do servidor MCP

Alguns clientes MCP (como o Cursor AI) têm um limite de 60 caracteres para o comprimento combinado do nome do servidor MCP + nome da ferramenta. Se você usar um nome de servidor mais longo em sua configuração (por exemplo, gtm-mcp-server-your-additional-long-name), algumas ferramentas podem ser filtradas.

Para evitar esse problema:

• Use nomes de servidor mais curtos em sua configuração MCP (por exemplo, gtm-mcp-server)

Limpando o cache MCP

Se você estiver conectando por meio de mcp-remote (Antigravity ou Claude Desktop configurado dessa forma), ele armazena todas as informações de credenciais dentro de ~/.mcp-auth (ou onde seu MCP_REMOTE_CONFIG_DIR aponta). Se você estiver tendo problemas persistentes, tente executar:

rm -rf ~/.mcp-auth

Em seguida, reinicie seu cliente MCP.

Teste suas alterações localmente

Qual fluxo de trabalho você precisa depende do que você alterou. A maioria das alterações está na primeira categoria — recorra à segunda apenas se estiver mexendo no próprio Worker.

Alterações em packages/core ou packages/cli

Esta é a lógica das ferramentas em si (esquemas, chamadas à API do GTM, tratamento de erros) — quase tudo que você corrigiria ou adicionaria está aqui. Você não precisa de um cliente OAuth do Google Cloud nem de configuração do Worker: compile a partir do código-fonte e execute a CLI diretamente com credenciais que você já possui.

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

Aponte seu cliente MCP para o build local em vez de npx — mesmas opções de credenciais do exemplo da CLI local do Claude Desktop acima; um token de acesso do OAuth Playground é a maneira mais rápida de testar uma única alteração:

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

Consulte o README da CLI para todas as opções de credenciais.

Alterações em apps/worker

Necessário apenas para o código do próprio servidor hospedado: o fluxo OAuth, roteamento, tratamento de sessão, as páginas de aprovação e status. Isso executa esse código em sua própria máquina com suas próprias credenciais OAuth do Google Cloud em vez de gtm-mcp.stape.ai.

1. Configure um cliente OAuth do Google Cloud

1. No Google Cloud Console, crie ou selecione um projeto e ative a API Tag Manager.
2. Vá para APIs e Serviços > Tela de consentimento OAuth e configure-a (Externo é suficiente). Enquanto o aplicativo estiver no status de publicação Teste, apenas contas listadas como usuários de teste podem fazer login.
3. Vá para Público, em Usuários de teste adicione sua própria conta do Google.
4. Vá para APIs e Serviços > Credenciais > Criar credenciais > ID do cliente OAuth, tipo Aplicativo da web.
5. Em URIs de redirecionamento autorizados, adicione http://localhost:8788/callback. (Você pode deixar Origens de JavaScript autorizadas vazio — este fluxo é apenas no lado do servidor, nenhum JS do navegador chama o Google diretamente.)
6. Salve e copie o ID do cliente e o Segredo do cliente gerados.

2. Configure as variáveis de ambiente locais

Copie o arquivo de exemplo e preencha os valores da etapa 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 é ignorado pelo git — é usado apenas localmente e nunca é commitado.

3. Inicie o servidor

npm install
npm run build
npm run dev

npm run build compila o pacote principal contra o qual o Worker é empacotado; npm run dev inicia o Worker em http://localhost:8788.

4. Aponte seu cliente MCP para o servidor local

Os conectores personalizados do Claude Desktop precisam de uma URL publicamente acessível, então mcp-remote é a única opção para apontar para localhost:

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

Reinicie o Claude Desktop. Uma janela do navegador abrirá para o fluxo OAuth do Google; faça login com a conta que você adicionou como usuário de teste na etapa 1.

Observação: se você já se conectou ao servidor hospedado (ou alterna entre local e hospedado), limpe o cache do mcp-remote primeiro (consulte Solução de problemas acima) e reinicie completamente seu cliente MCP; caso contrário, ele pode reutilizar uma conexão obsoleta/em cache.

Publicação

Versões e changelogs são gerenciados com Changesets. Junto com uma alteração que deve ser publicada, adicione:

npm run changeset

Ao mesclar em main, o fluxo de trabalho de publicação abre um PR "Version Packages"; mesclar esse PR publica no npm, primeiro o pacote principal e depois a CLI que depende dele. O Worker é privado e nunca é publicado — ele é implantado a partir de main a cada push.

Desenvolvimento

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

Pull requests executam tudo acima mais uma verificação do bundle do Worker e sinalizam alterações em um pacote publicado que chegam sem um changeset. Ambos @modelcontextprotocol/sdk e agents estão fixados em versões exatas no apps/worker. O SDK identifica os esquemas de ferramentas com instanceof, então todo o workspace precisa resolver uma única cópia, e os lançamentos do agents fixam a versão do SDK contra a qual foram compilados. Atualize-os juntos e faça a implantação com cuidado.

Recursos úteis

• Guia passo a passo: MCP Server para Google Tag Manager

Código aberto

O MCP Server para Google Tag Manager é desenvolvido e mantido pela Stape Team sob a licença Apache 2.0.