gtm-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Osama Humayun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+# GTM MCP Server
+
+Secure Model Context Protocol server for the Google Tag Manager API. It is read-only by default, with optional write tools (create/update only — **no delete**).
+
+## Quick start for team members (npx + Claude Code)
+
+This package is published **publicly** to the npm registry. You do **not** need to clone, build, or authenticate anything — Claude Code launches the server on demand via `npx`.
+
+1. Get your own Google OAuth credentials (see [OAuth setup](#setup) below — each person uses their own Google account that has GTM access). You need three values: `GTM_OAUTH_CLIENT_ID`, `GTM_OAUTH_CLIENT_SECRET`, `GTM_OAUTH_REFRESH_TOKEN`.
+
+2. Add this to your project's `.mcp.json` (keep it out of git — it holds your secrets):
+
+   ```json
+   {
+     "mcpServers": {
+       "gtm": {
+         "command": "npx",
+         "args": ["-y", "gtm-mcp-server"],
+         "env": {
+           "GTM_ENABLE_WRITE_TOOLS": "true",
+           "GTM_OAUTH_CLIENT_ID": "your-client-id",
+           "GTM_OAUTH_CLIENT_SECRET": "your-client-secret",
+           "GTM_OAUTH_REFRESH_TOKEN": "your-refresh-token"
+         }
+       }
+     }
+   }
+   ```
+
+3. Restart Claude Code. The `gtm` MCP connects automatically and exposes the `gtm_*` tools.
+
+Notes:
+- Set `GTM_ENABLE_WRITE_TOOLS` to `"false"` if you only want read/list tools. Write tools are create/update only — there is **no delete tool by design**.
+- Each member supplies their own OAuth credentials. No secret is shared.
+- Google may expire a test-app refresh token after ~7 days; re-run the OAuth flow to get a fresh one (or publish your OAuth consent screen to Production).
+
+## Publishing (maintainer)
+
+The package is published publicly to the npm registry.
+
+1. Log in to npm once:
+
+   ```bash
+   npm login
+   ```
+
+2. Publish (the `prepare` script builds `dist` first):
+
+   ```bash
+   npm publish
+   ```
+
+3. For updates, bump the version and publish again:
+
+   ```bash
+   npm version patch
+   npm publish
+   ```
+
+## Features
+
+- Express server with MCP Streamable HTTP transport at `/mcp`
+- Google Tag Manager API v2 integration
+- OAuth refresh token authentication, with optional service account JSON authentication
+- Read-only GTM scope by default: `https://www.googleapis.com/auth/tagmanager.readonly`
+- Optional write scope when enabled: `https://www.googleapis.com/auth/tagmanager.edit.containers`
+- MCP tools:
+  - `gtm_list_accounts`
+  - `gtm_list_containers`
+  - `gtm_list_tags`
+  - `gtm_list_triggers`
+  - `gtm_list_variables`
+  - `gtm_create_tag` when `GTM_ENABLE_WRITE_TOOLS=true`
+  - `gtm_create_trigger` when `GTM_ENABLE_WRITE_TOOLS=true`
+  - `gtm_create_variable` when `GTM_ENABLE_WRITE_TOOLS=true`
+- Server-side credential handling only. No frontend credential exposure.
+- Helmet, rate limiting, DNS rebinding host validation, restricted default CORS, sanitized errors.
+
+## Setup
+
+1. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+2. Create `.env` from `.env.example`.
+
+3. Create an OAuth client in Google Cloud:
+
+   - Application type: `Web application`
+   - Authorized JavaScript origins: leave empty
+   - Authorized redirect URI: `http://localhost:3000/oauth/google/callback`
+
+4. Add the OAuth client values to `.env`:
+
+   ```env
+   GTM_ENABLE_WRITE_TOOLS=false
+   GTM_OAUTH_CLIENT_ID=...
+   GTM_OAUTH_CLIENT_SECRET=...
+   GTM_OAUTH_REDIRECT_URI=http://localhost:3000/oauth/google/callback
+   GTM_OAUTH_REFRESH_TOKEN=
+   ```
+
+5. Start the local server:
+
+   ```bash
+   npm run dev
+   ```
+
+6. Open this URL in your browser and sign in with the Google account that has GTM access:
+
+   ```text
+   http://localhost:3000/oauth/google/start
+   ```
+
+7. After consent, the server terminal prints a refresh token. Add it to `.env`:
+
+   ```env
+   GTM_OAUTH_REFRESH_TOKEN=...
+   ```
+
+8. Restart the server.
+
+## Create Tags
+
+By default the server is read-only. To create tags, set:
+
+```env
+GTM_ENABLE_WRITE_TOOLS=true
+```
+
+Then run OAuth setup again from `/oauth/google/start` and replace `GTM_OAUTH_REFRESH_TOKEN`, because the old read-only token does not have write scope.
+
+Postman body:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "method": "tools/call",
+  "params": {
+    "name": "gtm_create_tag",
+    "arguments": {
+      "accountId": "123456",
+      "containerId": "78910",
+      "workspaceId": "3",
+      "name": "Postman test tag",
+      "type": "googtag",
+      "parameter": [
+        {
+          "type": "template",
+          "key": "tagId",
+          "value": "11212121"
+        }
+      ],
+      "firingTriggerId": ["2147479573"],
+      "tagFiringOption": "oncePerEvent"
+    }
+  }
+}
+```
+
+Create trigger example:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 6,
+  "method": "tools/call",
+  "params": {
+    "name": "gtm_create_trigger",
+    "arguments": {
+      "accountId": "123456",
+      "containerId": "78910",
+      "workspaceId": "3",
+      "name": "Postman click trigger",
+      "type": "click",
+      "filter": [
+        {
+          "type": "contains",
+          "parameter": [
+            {
+              "type": "template",
+              "key": "arg0",
+              "value": "{{Click Text}}"
+            },
+            {
+              "type": "template",
+              "key": "arg1",
+              "value": "Login"
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+Create variable example:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 7,
+  "method": "tools/call",
+  "params": {
+    "name": "gtm_create_variable",
+    "arguments": {
+      "accountId": "123456",
+      "containerId": "78910",
+      "workspaceId": "3",
+      "name": "Postman constant variable",
+      "type": "c",
+      "parameter": [
+        {
+          "type": "template",
+          "key": "value",
+          "value": "hello"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Service Account Alternative
+
+Use this only if GTM accepts your service account email in user management.
+
+Put the service account JSON outside public/frontend paths. The JSON file is ignored by git by default:
+
+   ```env
+   GTM_SERVICE_ACCOUNT_KEY_FILE=./service-account.json
+   ```
+
+   Alternatively, provide a base64-encoded JSON secret:
+
+   ```env
+   GTM_SERVICE_ACCOUNT_JSON_BASE64=...
+   ```
+
+Grant the service account view-only access to the relevant GTM accounts/containers.
+
+## Production
+
+```bash
+npm run build
+npm start
+```
+
+Bind `HOST` deliberately. The default is `127.0.0.1` for local-only access. If exposing the server remotely, terminate TLS in front of it, restrict network access, set `ALLOWED_HOSTS` to the expected hostnames, and set `ALLOWED_ORIGINS` only for trusted browser clients.
+
+## Tool Inputs
+
+`gtm_list_accounts` takes no input.
+
+`gtm_list_containers`:
+
+```json
+{
+  "accountId": "123456"
+}
+```
+
+`gtm_list_tags`, `gtm_list_triggers`, and `gtm_list_variables`:
+
+```json
+{
+  "accountId": "123456",
+  "containerId": "78910",
+  "workspaceId": "1"
+}
+```
+
+`workspaceId` is optional. If omitted, the server lists entities from every workspace in the container.
+
+Postman trigger list body:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 8,
+  "method": "tools/call",
+  "params": {
+    "name": "gtm_list_triggers",
+    "arguments": {
+      "accountId": "123456",
+      "containerId": "78910",
+      "workspaceId": "3"
+    }
+  }
+}
+```
+
+Postman variable list body:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 9,
+  "method": "tools/call",
+  "params": {
+    "name": "gtm_list_variables",
+    "arguments": {
+      "accountId": "123456",
+      "containerId": "78910",
+      "workspaceId": "3"
+    }
+  }
+}
+```
+
+## Security Notes
+
+- Keep service account JSON files out of git, frontend directories, static hosting, and client bundles.
+- Keep OAuth client secrets and refresh tokens server-side only.
+- Use a Google account or service account with the minimum GTM permissions needed for read-only access.
+- Keep `GTM_ENABLE_WRITE_TOOLS=false` unless GTM mutations are intentionally needed.
+- Set `ALLOWED_HOSTS` when binding to a non-localhost interface.
+- Do not enable broad CORS. Leave `ALLOWED_ORIGINS` empty unless a specific trusted browser client needs access.
+- Rotate the service account key if it is ever copied into logs, tickets, browser code, or public repositories.

package/dist/config/env.js

@@ -0,0 +1,101 @@
+import "dotenv/config";
+import { z } from "zod/v4";
+const booleanStringSchema = z
+    .string()
+    .optional()
+    .default("false")
+    .transform((value, ctx) => {
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "on"].includes(normalized)) {
+        return true;
+    }
+    if (["false", "0", "no", "off", ""].includes(normalized)) {
+        return false;
+    }
+    ctx.addIssue({
+        code: "custom",
+        message: "Expected boolean value: true, false, 1, 0, yes, no, on, or off."
+    });
+    return z.NEVER;
+});
+const envSchema = z
+    .object({
+    HOST: z.string().min(1).default("127.0.0.1"),
+    PORT: z.coerce.number().int().min(1).max(65535).default(3000),
+    MCP_PATH: z.string().regex(/^\//).default("/mcp"),
+    LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+    ALLOWED_HOSTS: z.string().optional().default(""),
+    ALLOWED_ORIGINS: z.string().optional().default(""),
+    GTM_ENABLE_WRITE_TOOLS: booleanStringSchema,
+    GTM_SERVICE_ACCOUNT_KEY_FILE: z.string().optional(),
+    GOOGLE_APPLICATION_CREDENTIALS: z.string().optional(),
+    GTM_SERVICE_ACCOUNT_JSON_BASE64: z.string().optional(),
+    GTM_OAUTH_CLIENT_ID: z.string().optional(),
+    GTM_OAUTH_CLIENT_SECRET: z.string().optional(),
+    GTM_OAUTH_REFRESH_TOKEN: z.string().optional(),
+    GTM_OAUTH_REDIRECT_URI: z.string().url().optional()
+})
+    .transform((env) => {
+    const serviceAccountKeyFile = env.GTM_SERVICE_ACCOUNT_KEY_FILE || env.GOOGLE_APPLICATION_CREDENTIALS;
+    const serviceAccountJsonBase64 = env.GTM_SERVICE_ACCOUNT_JSON_BASE64;
+    return {
+        host: env.HOST,
+        port: env.PORT,
+        mcpPath: env.MCP_PATH,
+        logLevel: env.LOG_LEVEL,
+        allowedHosts: env.ALLOWED_HOSTS.split(",")
+            .map((host) => host.trim())
+            .filter(Boolean),
+        allowedOrigins: env.ALLOWED_ORIGINS.split(",")
+            .map((origin) => origin.trim())
+            .filter(Boolean),
+        enableWriteTools: env.GTM_ENABLE_WRITE_TOOLS,
+        google: {
+            serviceAccountKeyFile,
+            serviceAccountJsonBase64,
+            oauthClientId: env.GTM_OAUTH_CLIENT_ID,
+            oauthClientSecret: env.GTM_OAUTH_CLIENT_SECRET,
+            oauthRefreshToken: env.GTM_OAUTH_REFRESH_TOKEN,
+            oauthRedirectUri: env.GTM_OAUTH_REDIRECT_URI ??
+                `http://${env.HOST}:${env.PORT}/oauth/google/callback`,
+            scopes: env.GTM_ENABLE_WRITE_TOOLS
+                ? ["https://www.googleapis.com/auth/tagmanager.edit.containers"]
+                : ["https://www.googleapis.com/auth/tagmanager.readonly"]
+        }
+    };
+})
+    .superRefine((config, ctx) => {
+    const hasKeyFile = Boolean(config.google.serviceAccountKeyFile);
+    const hasInlineJson = Boolean(config.google.serviceAccountJsonBase64);
+    const hasServiceAccount = hasKeyFile || hasInlineJson;
+    const hasCompleteOAuth = Boolean(config.google.oauthClientId &&
+        config.google.oauthClientSecret &&
+        config.google.oauthRefreshToken);
+    const hasOAuthSetup = Boolean(config.google.oauthClientId && config.google.oauthClientSecret && !config.google.oauthRefreshToken);
+    if (hasKeyFile && hasInlineJson) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Set only one service account source: GTM_SERVICE_ACCOUNT_KEY_FILE/GOOGLE_APPLICATION_CREDENTIALS or GTM_SERVICE_ACCOUNT_JSON_BASE64."
+        });
+    }
+    if (!hasServiceAccount && !hasCompleteOAuth && !hasOAuthSetup) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Set service account auth or OAuth auth. For OAuth setup, set GTM_OAUTH_CLIENT_ID and GTM_OAUTH_CLIENT_SECRET."
+        });
+    }
+    if (hasServiceAccount && (hasCompleteOAuth || hasOAuthSetup)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Use either service account auth or OAuth auth, not both."
+        });
+    }
+});
+export function loadConfig() {
+    const result = envSchema.safeParse(process.env);
+    if (!result.success) {
+        const details = z.prettifyError(result.error);
+        throw new Error(`Invalid environment configuration:\n${details}`);
+    }
+    return result.data;
+}

package/dist/google/auth.js

@@ -0,0 +1,36 @@
+import { google } from "googleapis";
+import { AppError } from "../shared/errors.js";
+function parseBase64ServiceAccount(value) {
+    try {
+        const decoded = Buffer.from(value, "base64").toString("utf8");
+        const credentials = JSON.parse(decoded);
+        if (!credentials.client_email || !credentials.private_key) {
+            throw new Error("Missing client_email or private_key.");
+        }
+        return credentials;
+    }
+    catch {
+        throw new AppError("Invalid GTM_SERVICE_ACCOUNT_JSON_BASE64 value.", 500, true);
+    }
+}
+export function createGoogleAuth(config) {
+    if (config.google.oauthClientId && config.google.oauthClientSecret) {
+        const oauthClient = new google.auth.OAuth2(config.google.oauthClientId, config.google.oauthClientSecret, config.google.oauthRedirectUri);
+        if (config.google.oauthRefreshToken) {
+            oauthClient.setCredentials({
+                refresh_token: config.google.oauthRefreshToken
+            });
+        }
+        return oauthClient;
+    }
+    if (config.google.serviceAccountJsonBase64) {
+        return new google.auth.GoogleAuth({
+            credentials: parseBase64ServiceAccount(config.google.serviceAccountJsonBase64),
+            scopes: [...config.google.scopes]
+        });
+    }
+    return new google.auth.GoogleAuth({
+        keyFile: config.google.serviceAccountKeyFile,
+        scopes: [...config.google.scopes]
+    });
+}

package/dist/google/oauth-setup.js

@@ -0,0 +1,37 @@
+import crypto from "node:crypto";
+import { google } from "googleapis";
+import { AppError } from "../shared/errors.js";
+const stateTtlMs = 10 * 60 * 1000;
+const pendingStates = new Map();
+function cleanupExpiredStates() {
+    const now = Date.now();
+    for (const [state, expiresAt] of pendingStates.entries()) {
+        if (expiresAt <= now) {
+            pendingStates.delete(state);
+        }
+    }
+}
+export function createOAuthSetupClient(config) {
+    if (!config.google.oauthClientId || !config.google.oauthClientSecret) {
+        throw new AppError("OAuth client ID and secret are not configured.", 500, true);
+    }
+    return new google.auth.OAuth2(config.google.oauthClientId, config.google.oauthClientSecret, config.google.oauthRedirectUri);
+}
+export function generateOAuthStartUrl(config) {
+    cleanupExpiredStates();
+    const state = crypto.randomBytes(32).toString("hex");
+    pendingStates.set(state, Date.now() + stateTtlMs);
+    const oauthClient = createOAuthSetupClient(config);
+    return oauthClient.generateAuthUrl({
+        access_type: "offline",
+        prompt: "consent",
+        scope: [...config.google.scopes],
+        state
+    });
+}
+export function consumeOAuthState(state) {
+    cleanupExpiredStates();
+    const expiresAt = pendingStates.get(state);
+    pendingStates.delete(state);
+    return Boolean(expiresAt && expiresAt > Date.now());
+}

package/dist/gtm/gtm-service.js

@@ -0,0 +1,157 @@
+import { google } from "googleapis";
+import { accountPath, containerPath, tagPath, workspacePath } from "./path.js";
+export class GoogleTagManagerService {
+    tagmanager;
+    constructor(auth) {
+        this.tagmanager = google.tagmanager({ version: "v2", auth });
+    }
+    async listAccounts() {
+        const accounts = [];
+        let pageToken;
+        do {
+            const response = await this.tagmanager.accounts.list({ pageToken });
+            accounts.push(...(response.data.account ?? []));
+            pageToken = response.data.nextPageToken ?? undefined;
+        } while (pageToken);
+        return accounts;
+    }
+    async listContainers(accountIdOrPath) {
+        const containers = [];
+        let pageToken;
+        do {
+            const response = await this.tagmanager.accounts.containers.list({
+                parent: accountPath(accountIdOrPath),
+                pageToken
+            });
+            containers.push(...(response.data.container ?? []));
+            pageToken = response.data.nextPageToken ?? undefined;
+        } while (pageToken);
+        return containers;
+    }
+    async listWorkspaces(accountIdOrPath, containerIdOrPath) {
+        const workspaces = [];
+        let pageToken;
+        do {
+            const response = await this.tagmanager.accounts.containers.workspaces.list({
+                parent: containerPath(accountIdOrPath, containerIdOrPath),
+                pageToken
+            });
+            workspaces.push(...(response.data.workspace ?? []));
+            pageToken = response.data.nextPageToken ?? undefined;
+        } while (pageToken);
+        return workspaces;
+    }
+    async listTags(accountIdOrPath, containerIdOrPath, workspaceIdOrPath) {
+        return this.listWorkspaceScopedEntities(accountIdOrPath, containerIdOrPath, workspaceIdOrPath, async (parent, pageToken) => {
+            const response = await this.tagmanager.accounts.containers.workspaces.tags.list({
+                parent,
+                pageToken
+            });
+            return {
+                items: response.data.tag ?? [],
+                nextPageToken: response.data.nextPageToken ?? undefined
+            };
+        });
+    }
+    async listTriggers(accountIdOrPath, containerIdOrPath, workspaceIdOrPath) {
+        return this.listWorkspaceScopedEntities(accountIdOrPath, containerIdOrPath, workspaceIdOrPath, async (parent, pageToken) => {
+            const response = await this.tagmanager.accounts.containers.workspaces.triggers.list({
+                parent,
+                pageToken
+            });
+            return {
+                items: response.data.trigger ?? [],
+                nextPageToken: response.data.nextPageToken ?? undefined
+            };
+        });
+    }
+    async listVariables(accountIdOrPath, containerIdOrPath, workspaceIdOrPath) {
+        return this.listWorkspaceScopedEntities(accountIdOrPath, containerIdOrPath, workspaceIdOrPath, async (parent, pageToken) => {
+            const response = await this.tagmanager.accounts.containers.workspaces.variables.list({
+                parent,
+                pageToken
+            });
+            return {
+                items: response.data.variable ?? [],
+                nextPageToken: response.data.nextPageToken ?? undefined
+            };
+        });
+    }
+    async createTag(input) {
+        const response = await this.tagmanager.accounts.containers.workspaces.tags.create({
+            parent: workspacePath(input.accountId, input.containerId, input.workspaceId),
+            requestBody: {
+                name: input.name,
+                type: input.type,
+                parameter: input.parameter,
+                firingTriggerId: input.firingTriggerId,
+                blockingTriggerId: input.blockingTriggerId,
+                tagFiringOption: input.tagFiringOption ?? "oncePerEvent"
+            }
+        });
+        return response.data;
+    }
+    async updateTag(input) {
+        const response = await this.tagmanager.accounts.containers.workspaces.tags.update({
+            path: tagPath(input.accountId, input.containerId, input.workspaceId, input.tagId),
+            fingerprint: input.fingerprint,
+            requestBody: {
+                name: input.name,
+                type: input.type,
+                parameter: input.parameter,
+                firingTriggerId: input.firingTriggerId,
+                blockingTriggerId: input.blockingTriggerId,
+                tagFiringOption: input.tagFiringOption
+            }
+        });
+        return response.data;
+    }
+    async createTrigger(input) {
+        const response = await this.tagmanager.accounts.containers.workspaces.triggers.create({
+            parent: workspacePath(input.accountId, input.containerId, input.workspaceId),
+            requestBody: {
+                name: input.name,
+                type: input.type,
+                filter: input.filter,
+                autoEventFilter: input.autoEventFilter,
+                customEventFilter: input.customEventFilter,
+                parameter: input.parameter
+            }
+        });
+        return response.data;
+    }
+    async createVariable(input) {
+        const response = await this.tagmanager.accounts.containers.workspaces.variables.create({
+            parent: workspacePath(input.accountId, input.containerId, input.workspaceId),
+            requestBody: {
+                name: input.name,
+                type: input.type,
+                parameter: input.parameter,
+                formatValue: input.formatValue
+            }
+        });
+        return response.data;
+    }
+    async listWorkspaceScopedEntities(accountIdOrPath, containerIdOrPath, workspaceIdOrPath, listPage) {
+        const workspaces = workspaceIdOrPath
+            ? [{ path: workspacePath(accountIdOrPath, containerIdOrPath, workspaceIdOrPath) }]
+            : await this.listWorkspaces(accountIdOrPath, containerIdOrPath);
+        // Fetch each workspace's entities concurrently. Pagination within a single
+        // workspace stays sequential (page tokens are inherently serial), but the
+        // per-workspace fetches no longer block each other — listing across N
+        // workspaces costs roughly one round-trip instead of N.
+        const results = await Promise.all(workspaces
+            .filter((workspace) => Boolean(workspace.path))
+            .map(async (workspace) => {
+            const items = [];
+            let pageToken;
+            do {
+                const page = await listPage(workspace.path, pageToken);
+                items.push(...page.items);
+                pageToken = page.nextPageToken;
+            } while (pageToken);
+            return { workspace, items };
+        }));
+        return results;
+    }
+}

package/dist/gtm/path.js

@@ -0,0 +1,20 @@
+export function accountPath(accountIdOrPath) {
+    return accountIdOrPath.startsWith("accounts/")
+        ? accountIdOrPath
+        : `accounts/${accountIdOrPath}`;
+}
+export function containerPath(accountIdOrPath, containerIdOrPath) {
+    return containerIdOrPath.startsWith("accounts/")
+        ? containerIdOrPath
+        : `${accountPath(accountIdOrPath)}/containers/${containerIdOrPath}`;
+}
+export function workspacePath(accountIdOrPath, containerIdOrPath, workspaceIdOrPath) {
+    return workspaceIdOrPath.startsWith("accounts/")
+        ? workspaceIdOrPath
+        : `${containerPath(accountIdOrPath, containerIdOrPath)}/workspaces/${workspaceIdOrPath}`;
+}
+export function tagPath(accountIdOrPath, containerIdOrPath, workspaceIdOrPath, tagIdOrPath) {
+    return tagIdOrPath.startsWith("accounts/")
+        ? tagIdOrPath
+        : `${workspacePath(accountIdOrPath, containerIdOrPath, workspaceIdOrPath)}/tags/${tagIdOrPath}`;
+}

package/dist/http/app.js

@@ -0,0 +1,111 @@
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import cors from "cors";
+import rateLimit from "express-rate-limit";
+import helmet from "helmet";
+import { consumeOAuthState, createOAuthSetupClient, generateOAuthStartUrl } from "../google/oauth-setup.js";
+import { createGtmMcpServer } from "../mcp/server.js";
+import { logError } from "../shared/errors.js";
+import { errorHandler, notFoundHandler } from "./middleware.js";
+function mcpMethodNotAllowed(_req, res) {
+    res.status(405).json({
+        jsonrpc: "2.0",
+        error: {
+            code: -32000,
+            message: "Method not allowed."
+        },
+        id: null
+    });
+}
+export function createApp(config, gtm) {
+    const app = createMcpExpressApp({
+        host: config.host,
+        allowedHosts: config.allowedHosts.length > 0 ? config.allowedHosts : undefined
+    });
+    app.disable("x-powered-by");
+    app.use(helmet());
+    app.use(rateLimit({
+        windowMs: 60_000,
+        limit: 120,
+        standardHeaders: "draft-7",
+        legacyHeaders: false
+    }));
+    if (config.allowedOrigins.length > 0) {
+        app.use(cors({
+            origin: config.allowedOrigins,
+            methods: ["POST", "GET"],
+            allowedHeaders: ["Content-Type", "Authorization", "Mcp-Session-Id"],
+            maxAge: 600
+        }));
+    }
+    app.get("/healthz", (_req, res) => {
+        res.status(200).json({ status: "ok" });
+    });
+    app.get("/oauth/google/start", (_req, res, next) => {
+        try {
+            res.redirect(generateOAuthStartUrl(config));
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.get("/oauth/google/callback", async (req, res, next) => {
+        try {
+            const code = typeof req.query.code === "string" ? req.query.code : undefined;
+            const state = typeof req.query.state === "string" ? req.query.state : undefined;
+            if (!code || !state || !consumeOAuthState(state)) {
+                res.status(400).send("Invalid or expired OAuth callback. Start again from /oauth/google/start.");
+                return;
+            }
+            const oauthClient = createOAuthSetupClient(config);
+            const { tokens } = await oauthClient.getToken(code);
+            if (!tokens.refresh_token) {
+                res
+                    .status(400)
+                    .send("Google did not return a refresh token. Revoke this app from your Google Account permissions, then start again.");
+                return;
+            }
+            console.log("\nAdd this to your .env as GTM_OAUTH_REFRESH_TOKEN:");
+            console.log(tokens.refresh_token);
+            console.log("");
+            res
+                .status(200)
+                .send("OAuth refresh token generated. Check the server terminal and add it to .env as GTM_OAUTH_REFRESH_TOKEN, then restart the server.");
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.post(config.mcpPath, async (req, res) => {
+        const server = createGtmMcpServer(gtm, config);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined
+        });
+        res.on("close", () => {
+            transport.close();
+            server.close();
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            logError(error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: "Internal server error."
+                    },
+                    id: null
+                });
+            }
+        }
+    });
+    app.get(config.mcpPath, mcpMethodNotAllowed);
+    app.delete(config.mcpPath, mcpMethodNotAllowed);
+    app.use(notFoundHandler);
+    app.use(errorHandler);
+    return app;
+}

package/dist/http/middleware.js

@@ -0,0 +1,14 @@
+import { AppError, logError } from "../shared/errors.js";
+export const notFoundHandler = (_req, _res, next) => {
+    next(new AppError("Not found.", 404, true));
+};
+export const errorHandler = (error, _req, res, _next) => {
+    logError(error);
+    const statusCode = error instanceof AppError ? error.statusCode : 500;
+    const message = error instanceof AppError && error.expose ? error.message : "Internal server error.";
+    res.status(statusCode).json({
+        error: {
+            message
+        }
+    });
+};

package/dist/index.js

@@ -0,0 +1,23 @@
+import { loadConfig } from "./config/env.js";
+import { createGoogleAuth } from "./google/auth.js";
+import { GoogleTagManagerService } from "./gtm/gtm-service.js";
+import { createApp } from "./http/app.js";
+const config = loadConfig();
+const auth = createGoogleAuth(config);
+const gtm = new GoogleTagManagerService(auth);
+const app = createApp(config, gtm);
+const httpServer = app.listen(config.port, config.host, () => {
+    console.log(`GTM MCP server listening on http://${config.host}:${config.port}${config.mcpPath}`);
+});
+function shutdown(signal) {
+    console.log(`Received ${signal}; shutting down.`);
+    httpServer.close((error) => {
+        if (error) {
+            console.error(error);
+            process.exit(1);
+        }
+        process.exit(0);
+    });
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/dist/mcp/server.js

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerGtmTools } from "./tools.js";
+export function createGtmMcpServer(gtm, config) {
+    const server = new McpServer({
+        name: "gtm-mcp-server",
+        version: "0.1.0"
+    }, {
+        capabilities: {
+            logging: {}
+        }
+    });
+    registerGtmTools(server, gtm, { enableWriteTools: config.enableWriteTools });
+    return server;
+}

package/dist/mcp/tools.js

@@ -0,0 +1,281 @@
+import { z } from "zod/v4";
+import { toSafeErrorMessage } from "../shared/errors.js";
+const gtmParameterSchema = z.lazy(() => z.object({
+    type: z
+        .string()
+        .min(1)
+        .describe("GTM parameter type, for example template, boolean, list, or map."),
+    key: z.string().min(1).optional().describe("Parameter key."),
+    value: z.string().optional().describe("Parameter value for template/string-like parameters."),
+    list: z
+        .array(gtmParameterSchema)
+        .optional()
+        .describe("Nested list items when type is list."),
+    map: z
+        .array(gtmParameterSchema)
+        .optional()
+        .describe("Nested map entries when type is map.")
+}));
+const gtmConditionSchema = z.object({
+    type: z.string().min(1).describe("GTM condition type, for example contains, equals, or cssSelector."),
+    parameter: z.array(gtmParameterSchema).optional().describe("Condition parameters.")
+});
+function jsonResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2)
+            }
+        ],
+        structuredContent: data
+    };
+}
+function errorResult(error) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: toSafeErrorMessage(error)
+            }
+        ],
+        isError: true
+    };
+}
+export function registerGtmTools(server, gtm, options) {
+    server.registerTool("gtm_list_accounts", {
+        title: "List GTM Accounts",
+        description: "List Google Tag Manager accounts visible to the configured Google auth identity.",
+        inputSchema: {}
+    }, async () => {
+        try {
+            return jsonResult({ accounts: await gtm.listAccounts() });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("gtm_list_containers", {
+        title: "List GTM Containers",
+        description: "List Google Tag Manager containers for an account.",
+        inputSchema: {
+            accountId: z
+                .string()
+                .min(1)
+                .describe("GTM account ID or full account path, for example 123456 or accounts/123456.")
+        }
+    }, async ({ accountId }) => {
+        try {
+            return jsonResult({ containers: await gtm.listContainers(accountId) });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("gtm_list_tags", {
+        title: "List GTM Tags",
+        description: "List Google Tag Manager tags for a container. If workspaceId is omitted, tags are listed from all workspaces.",
+        inputSchema: {
+            accountId: z.string().min(1).describe("GTM account ID or full account path."),
+            containerId: z.string().min(1).describe("GTM container ID or full container path."),
+            workspaceId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional GTM workspace ID or full workspace path.")
+        }
+    }, async ({ accountId, containerId, workspaceId }) => {
+        try {
+            return jsonResult({ workspaces: await gtm.listTags(accountId, containerId, workspaceId) });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("gtm_list_triggers", {
+        title: "List GTM Triggers",
+        description: "List Google Tag Manager triggers for a container. If workspaceId is omitted, triggers are listed from all workspaces.",
+        inputSchema: {
+            accountId: z.string().min(1).describe("GTM account ID or full account path."),
+            containerId: z.string().min(1).describe("GTM container ID or full container path."),
+            workspaceId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional GTM workspace ID or full workspace path.")
+        }
+    }, async ({ accountId, containerId, workspaceId }) => {
+        try {
+            return jsonResult({
+                workspaces: await gtm.listTriggers(accountId, containerId, workspaceId)
+            });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("gtm_list_variables", {
+        title: "List GTM Variables",
+        description: "List Google Tag Manager variables for a container. If workspaceId is omitted, variables are listed from all workspaces.",
+        inputSchema: {
+            accountId: z.string().min(1).describe("GTM account ID or full account path."),
+            containerId: z.string().min(1).describe("GTM container ID or full container path."),
+            workspaceId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional GTM workspace ID or full workspace path.")
+        }
+    }, async ({ accountId, containerId, workspaceId }) => {
+        try {
+            return jsonResult({
+                workspaces: await gtm.listVariables(accountId, containerId, workspaceId)
+            });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    if (!options.enableWriteTools) {
+        return;
+    }
+    server.registerTool("gtm_create_tag", {
+        title: "Create GTM Tag",
+        description: "Create a Google Tag Manager tag in a workspace. Requires GTM_ENABLE_WRITE_TOOLS=true and OAuth edit-containers scope.",
+        inputSchema: {
+            accountId: z.string().min(1).describe("GTM account ID or full account path."),
+            containerId: z.string().min(1).describe("Numeric GTM container ID or full container path."),
+            workspaceId: z.string().min(1).describe("GTM workspace ID or full workspace path."),
+            name: z.string().min(1).max(255).describe("Tag name."),
+            type: z
+                .string()
+                .min(1)
+                .default("googtag")
+                .describe("GTM tag type, for example googtag."),
+            parameter: z
+                .array(gtmParameterSchema)
+                .optional()
+                .describe("Raw GTM tag parameters accepted by the Tag Manager API."),
+            firingTriggerId: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe("Trigger IDs that fire this tag."),
+            blockingTriggerId: z
+                .array(z.string().min(1))
+                .optional()
+                .describe("Optional trigger IDs that block this tag."),
+            tagFiringOption: z
+                .enum(["unlimited", "oncePerEvent", "oncePerLoad"])
+                .default("oncePerEvent")
+                .describe("Tag firing option.")
+        }
+    }, async (args) => {
+        try {
+            const tag = await gtm.createTag(args);
+            return jsonResult({ tag });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("gtm_update_tag", {
+        title: "Update GTM Tag",
+        description: "Update an existing Google Tag Manager tag in a workspace. Requires GTM_ENABLE_WRITE_TOOLS=true and OAuth edit-containers scope.",
+        inputSchema: {
+            accountId: z.string().min(1).describe("GTM account ID or full account path."),
+            containerId: z.string().min(1).describe("Numeric GTM container ID or full container path."),
+            workspaceId: z.string().min(1).describe("GTM workspace ID or full workspace path."),
+            tagId: z.string().min(1).describe("GTM tag ID or full tag path."),
+            name: z.string().min(1).max(255).optional().describe("Tag name."),
+            type: z.string().min(1).optional().describe("GTM tag type, for example googtag."),
+            parameter: z
+                .array(gtmParameterSchema)
+                .optional()
+                .describe("Raw GTM tag parameters accepted by the Tag Manager API."),
+            firingTriggerId: z
+                .array(z.string().min(1))
+                .optional()
+                .describe("Trigger IDs that fire this tag."),
+            blockingTriggerId: z
+                .array(z.string().min(1))
+                .optional()
+                .describe("Optional trigger IDs that block this tag."),
+            tagFiringOption: z
+                .enum(["unlimited", "oncePerEvent", "oncePerLoad"])
+                .optional()
+                .describe("Tag firing option."),
+            fingerprint: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional GTM fingerprint for optimistic concurrency.")
+        }
+    }, async (args) => {
+        try {
+            const tag = await gtm.updateTag(args);
+            return jsonResult({ tag });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("gtm_create_trigger", {
+        title: "Create GTM Trigger",
+        description: "Create a Google Tag Manager trigger in a workspace. Requires GTM_ENABLE_WRITE_TOOLS=true and OAuth edit-containers scope.",
+        inputSchema: {
+            accountId: z.string().min(1).describe("GTM account ID or full account path."),
+            containerId: z.string().min(1).describe("Numeric GTM container ID or full container path."),
+            workspaceId: z.string().min(1).describe("GTM workspace ID or full workspace path."),
+            name: z.string().min(1).max(255).describe("Trigger name."),
+            type: z.string().min(1).describe("GTM trigger type, for example click, pageview, or customEvent."),
+            filter: z.array(gtmConditionSchema).optional().describe("Optional trigger filters."),
+            autoEventFilter: z
+                .array(gtmConditionSchema)
+                .optional()
+                .describe("Optional auto-event trigger filters."),
+            customEventFilter: z
+                .array(gtmConditionSchema)
+                .optional()
+                .describe("Optional custom event trigger filters."),
+            parameter: z
+                .array(gtmParameterSchema)
+                .optional()
+                .describe("Raw GTM trigger parameters accepted by the Tag Manager API.")
+        }
+    }, async (args) => {
+        try {
+            const trigger = await gtm.createTrigger(args);
+            return jsonResult({ trigger });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("gtm_create_variable", {
+        title: "Create GTM Variable",
+        description: "Create a Google Tag Manager variable in a workspace. Requires GTM_ENABLE_WRITE_TOOLS=true and OAuth edit-containers scope.",
+        inputSchema: {
+            accountId: z.string().min(1).describe("GTM account ID or full account path."),
+            containerId: z.string().min(1).describe("Numeric GTM container ID or full container path."),
+            workspaceId: z.string().min(1).describe("GTM workspace ID or full workspace path."),
+            name: z.string().min(1).max(255).describe("Variable name."),
+            type: z.string().min(1).describe("GTM variable type, for example v, jsm, or c."),
+            parameter: z
+                .array(gtmParameterSchema)
+                .optional()
+                .describe("Raw GTM variable parameters accepted by the Tag Manager API."),
+            formatValue: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Optional GTM variable formatValue.")
+        }
+    }, async (args) => {
+        try {
+            const variable = await gtm.createVariable(args);
+            return jsonResult({ variable });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/shared/errors.js

@@ -0,0 +1,39 @@
+export class AppError extends Error {
+    statusCode;
+    expose;
+    constructor(message, statusCode = 500, expose = false) {
+        super(message);
+        this.name = "AppError";
+        this.statusCode = statusCode;
+        this.expose = expose;
+    }
+}
+export function toSafeErrorMessage(error) {
+    if (error instanceof AppError && error.expose) {
+        return error.message;
+    }
+    const googleError = error;
+    const status = googleError.response?.status ?? googleError.code;
+    const statusText = googleError.response?.statusText;
+    const responseData = googleError.response?.data;
+    const responseError = responseData?.error;
+    const apiMessage = (typeof responseError === "object" ? responseError.message : responseError) ??
+        responseData?.error_description ??
+        googleError.errors?.map((item) => item.message).filter(Boolean).join("; ");
+    if (status) {
+        const prefix = `Google Tag Manager API request failed with status ${status}${statusText ? ` (${statusText})` : ""}.`;
+        return apiMessage ? `${prefix} ${apiMessage}` : prefix;
+    }
+    return "Request failed.";
+}
+export function logError(error) {
+    if (error instanceof Error) {
+        console.error({
+            name: error.name,
+            message: error.message,
+            stack: error.stack
+        });
+        return;
+    }
+    console.error({ error });
+}

package/dist/stdio.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config/env.js";
+import { createGoogleAuth } from "./google/auth.js";
+import { GoogleTagManagerService } from "./gtm/gtm-service.js";
+import { createGtmMcpServer } from "./mcp/server.js";
+// NOTE: In stdio mode, stdout is the MCP protocol channel. Anything written to
+// stdout will corrupt the JSON-RPC stream, so all diagnostics go to stderr.
+async function main() {
+    const config = loadConfig();
+    const auth = createGoogleAuth(config);
+    const gtm = new GoogleTagManagerService(auth);
+    const server = createGtmMcpServer(gtm, config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`GTM MCP server (stdio) ready. Write tools: ${config.enableWriteTools ? "enabled" : "disabled"}.`);
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "gtm-mcp-server",
+  "version": "0.1.0",
+  "description": "Secure MCP server for the Google Tag Manager API (read + create/update, no delete).",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "gtm-mcp-server": "dist/stdio.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "google-tag-manager",
+    "gtm",
+    "claude",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/osama-humayun-spursol/gtm-mcp-server.git"
+  },
+  "homepage": "https://github.com/osama-humayun-spursol/gtm-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/osama-humayun-spursol/gtm-mcp-server/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "start:stdio": "node dist/stdio.js",
+    "prepare": "tsc -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.7",
+    "express": "^5.1.0",
+    "express-rate-limit": "^7.5.0",
+    "googleapis": "^171.4.0",
+    "helmet": "^8.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}