@aiwerk/mcp-server-analytics

AIWerk 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.

Works against any AIWerk Analytics deployment: whoever gives you a share link (https://<host>/s/<token>) gives you exactly the data this server can read. Nothing more.

Tools (v0.1.0, 12 read-only)

• analytics_list_sites — configured sites (alias, name, domain, Search Console availability)
• analytics_get_overview — visitors, pageviews, bounce rate, avg. session duration + trend vs. previous period
• analytics_get_timeseries — daily visitors over the period
• analytics_get_top_pages — most viewed pages
• analytics_get_sources — traffic sources / referrers
• analytics_get_visitor_split — new vs. returning visitors
• analytics_get_devices, analytics_get_browsers, analytics_get_locations — audience breakdowns
• analytics_get_search_overview — Search Console totals: clicks, impressions, CTR, avg. position
• analytics_get_search_queries — top search keywords with clicks / impressions / CTR / position
• analytics_get_search_pages — top landing pages in Google Search

Every per-site tool takes site (alias, optional when only one site is configured) and period (1d | 7d | 30d | 90d, default 7d).

The 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.

Configuration

| Env var | Required | Default | Purpose | |---|---|---|---| | ANALYTICS_SHARE_TOKENS | yes | — | One or more share tokens, comma-separated (see formats below) | | ANALYTICS_BASE_URL | no | https://analytics.aiwerk.ch | Your analytics deployment | | ANALYTICS_API_TIMEOUT_MS | no | 30000 | Per-request timeout | | ANALYTICS_ALLOW_UNSAFE_BASE_URL | no | — | Dangerous override — see below |

ANALYTICS_SHARE_TOKENS formats

Each comma-separated entry is one site:

# Recommended: explicit alias
ANALYTICS_SHARE_TOKENS="mysite=mysite-a1b2c3..."

# Full share URL also works (token is extracted)
ANALYTICS_SHARE_TOKENS="mysite=https://analytics.example.com/s/mysite-a1b2c3..."

# Bare token: alias derived from the token slug
ANALYTICS_SHARE_TOKENS="mysite-a1b2c3..."

# Multiple sites
ANALYTICS_SHARE_TOKENS="shop=shop-a1b2...,blog=blog-c3d4..."

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.

Base URL safety

ANALYTICS_BASE_URL must use https:// — otherwise the server throws a configuration error before any token leaves the machine.

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.

Install

Two ways to run this server — pick the one that fits.

Option 1 — Hosted (zero setup)

No local runtime, no env vars on your machine — your share tokens are AES-256-GCM encrypted server-side.

1. Sign up at aiwerkmcp.com.
2. Install AIWerk Analytics from the catalog and paste your share token(s).
3. Point your MCP client (Claude.ai, Cursor, Hermes, …) at your hosted endpoint:

   https://bridge.aiwerk.ch/u/<your-user-id>/mcp

   with your Bearer token.

Option 2 — Self-hosted (npx)

ANALYTICS_SHARE_TOKENS="mysite=<token>" npx @aiwerk/mcp-server-analytics

Or install globally:

npm install -g @aiwerk/mcp-server-analytics
ANALYTICS_SHARE_TOKENS="mysite=<token>" mcp-server-analytics

Error taxonomy

Errors surface as MCP isError: true responses with distinct prefixes:

• Timeout: — request exceeded ANALYTICS_API_TIMEOUT_MS
• Network error: — connectivity problem
• Configuration error: — missing/invalid env vars, unknown site alias
• Analytics API error <status> — upstream HTTP error

Two 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).

Typical workflows

1. analytics_list_sites() → see what is configured and which sites have Search Console
2. analytics_get_overview({period: "30d"}) → monthly traffic report opener
3. analytics_get_timeseries + analytics_get_top_pages → "which day / which page drove the spike?"
4. analytics_get_search_queries({period: "90d"}) → SEO keyword review

Build / dev notes

• 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.
• Tests: npm test (vitest, no network — all fetch calls mocked).

About AIWerk MCP

Part of the AIWerk MCP platform — curated, signed MCP recipes served either as npm packages for self-hosting or through our multi-tenant hosted bridge (bridge.aiwerk.ch).

Other AIWerk MCP servers:

• @aiwerk/mcp-server-cal — Cal.com scheduling
• @aiwerk/mcp-server-imap — IMAP/SMTP email, provider-agnostic
• @aiwerk/mcp-server-wise — Wise (TransferWise), read-only
• @aiwerk/mcp-server-clawhub — ClawHub skill catalog

Browse the full catalog (20+ recipes including GitHub, Linear, Notion, Stripe, …) at aiwerkmcp.com.

Licence

MIT © 2026 AIWerk