yawa - Yet Another Web Analytics

yawa is a self-hosted web analytics platform with no UI. Instead of dashboards, you query your data through the Model Context Protocol (MCP), asking Claude or any compatible AI client questions about your traffic in plain language.

It requires no cookie banners or GDPR consent. Its tracking script is also super tiny.

❯ list my analytics sites

You have one registered site:

┌──────────────────────────────────────┬────────────────┬────────┐
│                  ID                  │    Hostname    │ Status │
├──────────────────────────────────────┼────────────────┼────────┤
│ 019ed922-33e5-7b9e-a072-963680861c6f │ yourdomain.com │ active │
└──────────────────────────────────────┴────────────────┴────────┘

❯ what are my top pages this week?

Top pages this week (Jun 15–18):

┌───────────────────┬──────────┬───────────┐
│       Page        │ Visitors │ Pageviews │
├───────────────────┼──────────┼───────────┤
│ / (homepage)      │ 312      │ 489       │
│ /blog             │ 201      │ 334       │
│ /about            │ 98       │ 121       │
│ /blog/hello-world │ 87       │ 103       │
└───────────────────┴──────────┴───────────┘

Your homepage leads, with the blog close behind.

Motivation

yawa grew out of my experience building Juno, for which I had already implemented a custom privacy-friendly analytics solution. When it was deprecated, I needed to move my projects. Since I already had the logic and some reusable code, I thought: why not build yet another web analytics, again 😅.

I also find it interesting to skip the dashboard entirely and rely solely on an MCP server for querying data.

Related MCP server: Gizmo Analytics

How it works

Yet another web analytics has three moving parts.

Your app or website sends analytics with a lightweight JavaScript library (yawa-tracker) that collects page views, custom events and Web Vitals.

On your self-hosted server, you deploy a Docker container that exposes an API and MCP server. It receives the events and stores them in an embedded DuckDB database, and provides 26+ analytics tools over the Model Context Protocol.

Lastly, connect your MCP client (Claude Code/Desktop, Codex, or any MCP-compatible client) to your endpoint and query your data in natural language.

Quick Start

Run the server on any VPS or locally if you just want to give it a spin.

1. Create a docker-compose.yml

services:
  app:
    image: peterpeterparker/yawa:latest
    ports:
      - "3000:3000"
    volumes:
      - yawa-data:/data
    environment:
      - YAWA_SESSION_SECRET=${YAWA_SESSION_SECRET}
    restart: unless-stopped

volumes:
  yawa-data:

2. Generate a secret

Optional, but improves visitor counting accuracy when generating the session IDs.

echo "YAWA_SESSION_SECRET=$(openssl rand -base64 32)" > .env

3. Start the server

docker compose up -d

Create an access token

docker exec -it <container-name> ./cli token create --name mytoken

Copy the token - it will only be shown once.

Register your site

docker exec -it <container-name> ./cli site create --hostname yourdomain.com

Connect your MCP client

Once your server is running, connect any MCP-compatible client using the token created above.

Claude Code

claude mcp add yawa https://your-server.com/mcp --transport http \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude (web)

Claude web currently requires OAuth for MCP connections. Bearer token support is not yet available. Follow this issue, which aims to add support for custom HTTP headers, for updates.

Once connected, start by listing your sites:

List my analytics sites
What are my top pages this week?
Show me web vitals for my homepage.
Which UTM campaigns are driving the most visitors?
etc.

Codex

export YAWA_TOKEN="YOUR_TOKEN"

codex mcp add yawa \
  --url https://your-server.com/mcp \
  --bearer-token-env-var YAWA_TOKEN

Mistral (Vibe)

Go to Context -> Connectors -> Add a Custom MCP Connector. Enter your server URL, wait for detection, then enter your Bearer token.

Cursor

Add to your mcp.json:

{
  "mcpServers": {
    "yawa": {
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Install the tracker

There are two ways to add the tracker to your site.

Script tag

Add this to your site's <head>:

<script type="module" src="https://your-yawa-server.com/static/yawa.js"></script>

The script derives the server URL from where it was loaded, so no further configuration is needed. It automatically tracks page views on load and navigation. Web Vitals collection is not available with this method; use the npm package below if you need that.

npm

npm install yawa-tracker

import { init } from "yawa-tracker";

const cleanup = init({
  serverUrl: "https://your-yawa-server.com",
});

This automatically tracks page views on load and navigation (SPA-friendly via history.pushState and popstate).

Custom events

To track a custom event, call track with a name and optional metadata:

import { track } from "yawa-tracker";

track({ name: "signup", metadata: { plan: "pro" } });

Keys and values must be strings, with a maximum of 10 keys and 200 characters per key/value.

Web Vitals

Core Web Vitals (CLS, FCP, INP, LCP, TTFB) can also be collected by enabling the option when initializing the tracker:

import { init } from "yawa-tracker";

const cleanup = init({
  serverUrl: "https://your-yawa-server.com",
  webVitals: true,
});

API

Options

MCP tools

Once connected, the following tools are available:

Sites

Page views

Custom events

Web Vitals

Configuration

Development

Clone the repo and run the app locally.

Setup

git clone https://github.com/peterpeterparker/yawa.git
cd yawa
bun install --frozen-lockfile

Run locally

bun run --filter yawa-app dev

The app server starts on http://localhost:3000 (events and MCP) and http://localhost:9999 (CLI only).

CLI

bun run --filter yawa-cli dev token create --name test
bun run --filter yawa-cli dev site create --hostname localhost

Run tests

bun test

Build

bun run --filter yawa-app build

License

MIT