GTM MCP

Run from the gtm-mcp repository root unless --prefix is used.

Execute setup

1. •Install dependencies.

npm install

1. •Run interactive setup.

npm run setup

1. •Ensure .env values are unquoted. Use: GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... GOOGLE_REDIRECT_URI=http://127.0.0.1:8085 GTM_MCP_TOKEN_PATH=.gtm-mcp/tokens.json

Register MCP servers

Choose only what the user needs.

1. •Codex global registration:

npm run register:codex

1. •Claude user registration (default):

npm run register:claude

1. •Claude user registration (explicit):

npm run register:claude:user

1. •Claude project registration:

npm run register:claude:project

1. •Claude local registration:

npm run register:claude:local

If called from another directory, register with:

npm --prefix /absolute/path/to/gtm-mcp run register:codex
npm --prefix /absolute/path/to/gtm-mcp run register:claude

Run first OAuth flow

1. •Open a new Codex/Claude session after MCP registration.
2. •Call oauth_get_consent_url.
3. •Open returned URL in an external browser.
4. •Approve and copy the authorization code.
5. •Call oauth_exchange_code with the code.
6. •Verify with oauth_status.

Use GTM MCP tools in practice

After OAuth is complete, prefer this sequence.

1. •Discover resources.
   • •gtm_list_accounts
   • •gtm_list_containers with accountId
   • •gtm_list_workspaces with accountId, containerId
2. •Inspect existing setup.
   • •gtm_list_tags
   • •gtm_list_triggers
   • •gtm_list_variables
3. •Create/update resources in workspace.
   • •gtm_create_tag / gtm_update_tag
   • •gtm_create_trigger / gtm_update_trigger
   • •gtm_create_variable / gtm_update_variable
4. •Delete only when explicitly requested.
   • •gtm_delete_tag
   • •gtm_delete_trigger
   • •gtm_delete_variable

Common payload shape reminders:

• •accountId, containerId, workspaceId accept raw IDs or full path fragments.
• •tag, trigger, variable are passed as JSON objects from GTM API schema.
• •For unsupported endpoints, use gtm_request.

gtm_request examples:

• •List accounts:
  • •{ "method": "GET", "path": "/accounts" }
• •List container versions:
  • •{ "method": "GET", "path": "/accounts/{accountId}/containers/{containerId}/versions" }

Troubleshoot quickly

1. •Error 400: invalid_request on Google sign-in:
   • •Remove quotes from client_id and redirect_uri.
   • •Ensure redirect URI is exactly http://127.0.0.1:8085 in both Google Cloud and .env.
2. •MCP not visible:
   • •Re-run the corresponding register:* command.
   • •Start a new Codex/Claude session.
3. •Existing gtm entry not updated:
   • •Current scripts skip when same name exists.
   • •Remove manually then re-run register command if update is required.