{"_id":"@aiwerk/mcp-server-analytics","name":"@aiwerk/mcp-server-analytics","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aiwerk/mcp-server-analytics","version":"0.1.0","description":"AIWerk Analytics MCP server — read-only website traffic + Search Console data via share tokens","type":"module","main":"dist/src/server.js","bin":{"mcp-server-analytics":"dist/src/server.js"},"scripts":{"gen-version":"node scripts/gen-version.mjs","prebuild":"npm run gen-version","build":"tsc -p tsconfig.json","start":"node dist/src/server.js","predev":"npm run gen-version","dev":"tsc --watch","pretest":"npm run gen-version","test":"vitest run","prepublishOnly":"bash $HOME/agent-memory/commons/scripts/prepublish-safety.sh && npm run build && npm test"},"engines":{"node":">=18.0.0"},"keywords":["mcp","mcp-server","analytics","web-analytics","ga4","search-console","seo"],"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/AIWerk/mcp-server-analytics.git"},"homepage":"https://aiwerkmcp.com","bugs":{"url":"https://github.com/AIWerk/mcp-server-analytics/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.19.1","zod":"^3.25.76"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.5.0","vitest":"^3.2.1"},"gitHead":"52e067ec19bbefa78716e47193d157b63cdcf854","_id":"@aiwerk/mcp-server-analytics@0.1.0","_nodeVersion":"18.19.1","_npmVersion":"9.2.0","dist":{"integrity":"sha512-nL/+8gEFTafQeiQYXk2/FSXn31cQtd0CRSy4CHShPkuOzFJmUkCg6G8s7Xgg5WxwbF2DPMRk+A3gxsd4jT1PiA==","shasum":"f55f50582dffb4c32a740da1ae4e149e5c31c59e","tarball":"https://registry.npmjs.org/@aiwerk/mcp-server-analytics/-/mcp-server-analytics-0.1.0.tgz","fileCount":13,"unpackedSize":30071,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBbkMF/iA8F31UmYRI417eUOaAb3wD7obtVMnIdT94BlAiBxq+FLGRuVsT+5xwScEkRlnUcOS148troWlqaqFvkElA=="}]},"_npmUser":{"name":"agbergsmann","email":"kontakt@aiwerk.ch"},"directories":{},"maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-analytics_0.1.0_1783081033019_0.8230093225331099"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T12:17:12.818Z","0.1.0":"2026-07-03T12:17:13.205Z","modified":"2026-07-03T12:17:13.465Z"},"maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"description":"AIWerk Analytics MCP server — read-only website traffic + Search Console data via share tokens","homepage":"https://aiwerkmcp.com","keywords":["mcp","mcp-server","analytics","web-analytics","ga4","search-console","seo"],"repository":{"type":"git","url":"git+https://github.com/AIWerk/mcp-server-analytics.git"},"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"bugs":{"url":"https://github.com/AIWerk/mcp-server-analytics/issues"},"license":"MIT","readme":"# @aiwerk/mcp-server-analytics\n\nAIWerk Analytics MCP server. Read-only website traffic and Google Search Console data via dashboard share tokens — no Google account, no OAuth, just the share link.\n\nWorks against any [AIWerk Analytics](https://analytics.aiwerk.ch) deployment: whoever gives you a share link (`https://<host>/s/<token>`) gives you exactly the data this server can read. Nothing more.\n\n## Tools (v0.1.0, 12 read-only)\n\n- `analytics_list_sites` — configured sites (alias, name, domain, Search Console availability)\n- `analytics_get_overview` — visitors, pageviews, bounce rate, avg. session duration + trend vs. previous period\n- `analytics_get_timeseries` — daily visitors over the period\n- `analytics_get_top_pages` — most viewed pages\n- `analytics_get_sources` — traffic sources / referrers\n- `analytics_get_visitor_split` — new vs. returning visitors\n- `analytics_get_devices`, `analytics_get_browsers`, `analytics_get_locations` — audience breakdowns\n- `analytics_get_search_overview` — Search Console totals: clicks, impressions, CTR, avg. position\n- `analytics_get_search_queries` — top search keywords with clicks / impressions / CTR / position\n- `analytics_get_search_pages` — top landing pages in Google Search\n\nEvery per-site tool takes `site` (alias, optional when only one site is configured) and `period` (`1d` | `7d` | `30d` | `90d`, default `7d`).\n\nThe three `search_*` tools require the site to have Search Console connected — `analytics_list_sites` shows `has_search_console` per site, and the error message tells the model exactly that if it asks anyway.\n\n## Configuration\n\n| Env var | Required | Default | Purpose |\n|---|---|---|---|\n| `ANALYTICS_SHARE_TOKENS` | yes | — | One or more share tokens, comma-separated (see formats below) |\n| `ANALYTICS_BASE_URL` | no | `https://analytics.aiwerk.ch` | Your analytics deployment |\n| `ANALYTICS_API_TIMEOUT_MS` | no | `30000` | Per-request timeout |\n| `ANALYTICS_ALLOW_UNSAFE_BASE_URL` | no | — | **Dangerous override** — see below |\n\n### `ANALYTICS_SHARE_TOKENS` formats\n\nEach comma-separated entry is one site:\n\n```bash\n# Recommended: explicit alias\nANALYTICS_SHARE_TOKENS=\"mysite=mysite-a1b2c3...\"\n\n# Full share URL also works (token is extracted)\nANALYTICS_SHARE_TOKENS=\"mysite=https://analytics.example.com/s/mysite-a1b2c3...\"\n\n# Bare token: alias derived from the token slug\nANALYTICS_SHARE_TOKENS=\"mysite-a1b2c3...\"\n\n# Multiple sites\nANALYTICS_SHARE_TOKENS=\"shop=shop-a1b2...,blog=blog-c3d4...\"\n```\n\n**The share token is the credential.** Anyone holding it can read that site's statistics. Treat it like an API key: keep it in env / a secret store, never commit it. This server never echoes tokens back in tool output or error messages.\n\n### Base URL safety\n\n`ANALYTICS_BASE_URL` must use `https://` — otherwise the server throws a configuration error before any token leaves the machine.\n\n> **Dangerous override:** set `ANALYTICS_ALLOW_UNSAFE_BASE_URL=1` to allow `http://` (e.g. a local dev instance). Only use for local testing. Your share tokens will be sent in cleartext to whatever host you configure.\n\n## Install\n\nTwo ways to run this server — pick the one that fits.\n\n### Option 1 — Hosted (zero setup)\n\nNo local runtime, no env vars on your machine — your share tokens are AES-256-GCM encrypted server-side.\n\n1. Sign up at **[aiwerkmcp.com](https://aiwerkmcp.com)**.\n2. Install **AIWerk Analytics** from the catalog and paste your share token(s).\n3. Point your MCP client (Claude.ai, Cursor, Hermes, …) at your hosted endpoint:\n   ```\n   https://bridge.aiwerk.ch/u/<your-user-id>/mcp\n   ```\n   with your Bearer token.\n\n### Option 2 — Self-hosted (npx)\n\n```bash\nANALYTICS_SHARE_TOKENS=\"mysite=<token>\" npx @aiwerk/mcp-server-analytics\n```\n\nOr install globally:\n\n```bash\nnpm install -g @aiwerk/mcp-server-analytics\nANALYTICS_SHARE_TOKENS=\"mysite=<token>\" mcp-server-analytics\n```\n\n## Error taxonomy\n\nErrors surface as MCP `isError: true` responses with distinct prefixes:\n\n- `Timeout:` — request exceeded `ANALYTICS_API_TIMEOUT_MS`\n- `Network error:` — connectivity problem\n- `Configuration error:` — missing/invalid env vars, unknown site alias\n- `Analytics API error <status>` — upstream HTTP error\n\nTwo 404 cases get rewritten into actionable messages: a site without Search Console (try a traffic tool instead) and a revoked/mistyped share token (check `ANALYTICS_SHARE_TOKENS`).\n\n## Typical workflows\n\n1. `analytics_list_sites()` → see what is configured and which sites have Search Console\n2. `analytics_get_overview({period: \"30d\"})` → monthly traffic report opener\n3. `analytics_get_timeseries` + `analytics_get_top_pages` → \"which day / which page drove the spike?\"\n4. `analytics_get_search_queries({period: \"90d\"})` → SEO keyword review\n\n## Build / dev notes\n\n- `src/version.ts` is **generated** from `package.json` by `scripts/gen-version.mjs` (runs as `prebuild` / `predev` / `pretest`). The file IS committed so a fresh clone compiles immediately.\n- Tests: `npm test` (vitest, no network — all fetch calls mocked).\n\n## About AIWerk MCP\n\nPart of the **[AIWerk MCP platform](https://aiwerkmcp.com)** — curated, signed MCP recipes served either as npm packages for self-hosting or through our multi-tenant hosted bridge (`bridge.aiwerk.ch`).\n\nOther AIWerk MCP servers:\n\n- [@aiwerk/mcp-server-cal](https://github.com/AIWerk/mcp-server-cal) — Cal.com scheduling\n- [@aiwerk/mcp-server-imap](https://github.com/AIWerk/mcp-server-imap) — IMAP/SMTP email, provider-agnostic\n- [@aiwerk/mcp-server-wise](https://github.com/AIWerk/mcp-server-wise) — Wise (TransferWise), read-only\n- [@aiwerk/mcp-server-clawhub](https://github.com/AIWerk/mcp-server-clawhub) — ClawHub skill catalog\n\nBrowse the full catalog (20+ recipes including GitHub, Linear, Notion, Stripe, …) at [aiwerkmcp.com](https://aiwerkmcp.com).\n\n## Licence\n\nMIT © 2026 AIWerk\n","readmeFilename":"README.md","_rev":"1-625ce0526e4f47afd29b894e56db5921"}