Self-hosted web analytics you query by asking an AI agent, instead of reading a dashboard.
A script tag on your site sends events to a server you run. Then you ask — in Claude, Cursor, or any MCP client — and the agent answers from your own data:
You: Did anything unusual happen on the site last week?
Agent: Interaction events were up about 35% last Tuesday — almost entirely
outbound_link_clickon your GitHub link, not more page views. Worth checking what pointed there that day.
Genug is German for enough: just enough analytics to answer your questions, and nothing to operate beyond one process and one file.
Status: alpha. Running in production on the maintainer's own sites. The shape of things may still change before 1.0; see CHANGELOG.md.
- Ask, don't read. 35 MCP tools, each answering one question a site owner actually asks: top pages, where traffic comes from, which campaign converted, whether a drop is real. Every tool can be narrowed to a segment, so "where did the buyers of product X come from" is one question.
- Radically small. One Node process, one SQLite file. Your own events are one JSON file each, live the moment you save. Several of your own sites can share one installation, asked about together or one at a time, with visitors never linked across them.
- Privacy by architecture. No cookie by default: the visitor ID is a daily-changing hash, and the address it comes from is never stored in the database. An optional country lookup reads the shortened address on your own server and stores only the country code. Query strings are filtered before storage. Consent switches on a first-party cookie, and an opt-out is built in.
A small cockpit is there for when you want to look rather than ask:
-
Point a subdomain at your server, such as
data.your-domain.com, as DNS only (no Cloudflare proxy). -
Install it on a fresh Ubuntu server. It asks for the hostname, your site's origin and a password, and sets up HTTPS:
curl -fsSL https://genug-analytics.com/install.sh | sudo bash -
Put the script on your site, early in
<head>:<script> window.genugAnalyticsConfig = { enableAutoPageTracking: true }; </script> <script defer src="https://data.your-domain.com/client.js"></script>
-
Connect your agent. For Claude Code:
claude mcp add --transport http genug https://data.your-domain.com/mcp \ --header "Authorization: Bearer YOUR_MCP_API_KEY"Then ask: "What were my top pages this week, and where did that traffic come from?"
Step by step, with troubleshooting: getting started. Coolify or Docker by hand: deploying.
Before going live, decide what your privacy notice says, how long you keep data (13 months by default), and whether you need a consent banner. That last one is a question for your lawyer. Privacy lists what Genug stores and has a template.
Page views, outbound clicks and file downloads are built in. The last
two are off until you add enableAutoLinkTracking: true to the config.
Define anything else in the cockpit or as one JSON file, then send it:
window.genugAnalytics.track("order_completed", { order_total: 49.9 });<button data-genug-on-click="cta_click">Upgrade</button>An event that doesn't match its definition is rejected and counted in the cockpit, with the reason. More in client.md.
- Connecting an agent: every client, telling the agent about your site, what leaves your server
- The client script: consent, single-page apps, custom events
- Privacy: what is stored, and a policy template
- Operations: capacity, retention, backups, restore, erasure, export
- Weekly digest: a ready-made prompt
You run your own copy, so change it. Three recipes are written to be followed end to end, by you or by an AI coding assistant:
An assistant working in this repo reads AGENTS.md, the rules that keep a change from producing numbers that look right but aren't. The reasoning is in docs/decisions.md.
npm install
npm run build && npm test && npm run lintTo send a fix back, see CONTRIBUTING.md. Report a security problem privately, as SECURITY.md describes, not in an issue.
MIT — see LICENSE.