google-insights
by Aleloca
README.md
# google-insights
An MCP server and Claude Code skill that give Claude access to Google Search Console, Google Analytics 4 and Google Tag Manager through service-account keys.
## Why
If you manage several sites, answering "how is the SEO / traffic doing?" means finding the right account, property and credentials every time. google-insights discovers which key, property and container belong to a domain, so you can just ask in any project and get an analysis based on real data. Reads are free; writes always need your explicit approval.
## Features
- **Read tools**: Search Console queries (with automatic previous-period comparison), URL inspection, sitemaps; GA4 reports, realtime, metadata and admin listings; Tag Manager tags, triggers, variables, versions and workspaces.
- **Confirm-gated write tools**: submit a sitemap, create GA4 key events and custom dimensions, upsert/publish/discard in GTM. Every write is a two-step flow (preview, then confirm).
- **GTM `claude-*` workspaces**: Claude never edits the default workspace. Each intervention happens in a dedicated `claude-<date>-<slug>` workspace, so your manual changes are never published by accident.
- **Auto-discovery by domain**: `resolve example.com` finds the right key, Search Console site, GA4 property and GTM container. No per-repo configuration.
- **A skill** that encodes how to do the analysis: pick before/after periods, skip the last 3 days of GSC data, report deltas and caveats.
## Requirements
- Node >= 22.
- A Google Cloud service account per site (or per group of sites), in a project with these APIs enabled: Search Console API, Google Analytics Admin API, Google Analytics Data API, Tag Manager API.
- The service-account email added as a user in Search Console, GA4 and Tag Manager for each site it should see (viewer is enough for reads in Search Console and GA4; Tag Manager needs edit rights to write).
## Install
```
git clone https://github.com/Aleloca/google-insights.git
cd google-insights
npm i
claude mcp add --scope user google-insights -- node <abs path>/src/server.js
mkdir -p ~/.claude/skills/google-insights && cp skill/SKILL.md ~/.claude/skills/google-insights/
```
Start a new Claude Code session to pick up the server and skill.
## Keys
Put one service-account JSON key per file in `~/.secrets/google/`. Override the directory with the `GOOGLE_INSIGHTS_KEYS_DIR` environment variable. The file name (without `.json`) is the key name.
## Check setup
```
npm run doctor
```
Lists the loaded keys and what each can see per service, with hints for failures (API not enabled, missing permission).
## How approvals work
Write tools (`gsc_submit_sitemap`, `ga4_create_key_event`, `ga4_create_custom_dimension`, `gtm_upsert`, `gtm_publish`, `gtm_discard_workspace`) first return a preview and a short-lived `confirmToken` without changing anything. Claude shows you the preview, you say yes, and only then does it repeat the call with the token. If the target changed since the preview, the call is refused and a new preview is needed. GTM edits go to a dedicated `claude-<date>-<slug>` workspace and are never published without a separate approval. This is enforced by the server, so it holds even when Claude Code runs in an auto-approve mode.
## Recommended permissions
In `~/.claude/settings.json`, allow only the 10 read tools so writes keep prompting:
```json
"permissions": { "allow": [
"mcp__google-insights__discover",
"mcp__google-insights__resolve",
"mcp__google-insights__gsc_query",
"mcp__google-insights__gsc_inspect_url",
"mcp__google-insights__gsc_sitemaps",
"mcp__google-insights__ga4_report",
"mcp__google-insights__ga4_realtime",
"mcp__google-insights__ga4_metadata",
"mcp__google-insights__ga4_admin_list",
"mcp__google-insights__gtm_list"
] }
```
## Security notes
- Private keys never leave the process: they are only used to obtain Google access tokens, and tools return just the key file name and `client_email`.
- Keep keys outside the repo (default `~/.secrets/google`). `.gitignore` excludes `keys/`, `*.key.json` and `.env` as a safety net.
- Grant each service account the minimum access it needs; use viewer roles if you only want reads.
## License
MIT, see [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues