gtm-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

npm run build    # Compile TypeScript to dist/
npm run dev      # Watch mode for development
npm start        # Run the compiled server

Testing

Test the MCP server with the inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Requires GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to a service account JSON key file.

Architecture

This is an MCP (Model Context Protocol) server that exposes Google Tag Manager API operations as tools. It uses service account authentication (no OAuth).

Source Structure

• index.ts - Entry point; creates McpServer instance (version read from package.json) and registers all tool modules
• auth.ts - getTagManagerClient() initializes Google Auth with service account credentials; the client is memoized module-level
• schemas.ts - Shared Zod schemas: gtmId (numeric ID validation), accountScope/containerScope/workspaceScope input shapes, recursive gtmParameterSchema, triggerFilterSchema
• helpers.ts - API path builders, shared annotation constants (READ_ONLY/CREATE/DESTRUCTIVE), textResult/errorResult builders (errorResult extracts Gaxios HTTP status + API error message), pagination helpers
• formatters.ts - Text formatting functions for GTM resources; long parameter values are truncated in text output (full data stays in structuredContent)
• tools/ - Each file exports a register*Tools(server) function that registers related MCP tools:
  • accounts.ts (1 tool)
  • containers.ts (2 tools)
  • workspaces.ts (4 tools)
  • tags.ts (5 tools)
  • triggers.ts (5 tools)
  • variables.ts (5 tools)
  • versions.ts (4 tools)
  • builtInVariables.ts (3 tools)

Tool Pattern

All tools follow the same structure:

1. Define tool with Zod input schema (built from shared scope shapes in schemas.ts) and shared annotation constants from helpers.ts
2. Handler calls getTagManagerClient(), makes GTM API request using path builders from helpers.ts
3. Returns formatted text + raw data via textResult(text, structured); list tools support page_token and surface nextPageToken
4. Errors caught and returned via errorResult(label, error) with isError: true
5. Update tools do read-merge-write and pass the entity's fingerprint for optimistic locking