yawa - Yet Another Web Analytics

Important

yawa is in early development. APIs, configuration, and data formats may change without notice. Use in production at your own risk.

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.

Note

I do not plan to implement features such as user journeys or funnels as I do not have those requirements myself. Other solutions handle that well. Feel free to contribute or hire me if needed.

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.

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:

Generate a secret

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

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

Start the server

docker compose up -d

Create an access token

Note

Tokens are used to authenticate the MCP client.

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

Copy the token - it will only be shown once.

Register your site

Note

yawa supports multiple sites.

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"

Tip

Add --scope user to make it available across all your projects.

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

Note

Available with the npm package only.

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

Function	Description
`init(options)`	Initialize the tracker. Returns a cleanup function.
`track(data)`	Fire-and-forget custom event.
`trackAsync(data)`	Async custom event.
`visit()`	Fire-and-forget page view tracking.
`visitAsync()`	Async page view tracking.

Options

Option	Required	Description
`serverUrl`	Yes	URL of your yawa server.
`webVitals`	No	Enable Web Vitals tracking. Defaults to `false`.

MCP tools

Once connected, the following tools are available:

Sites

Tool	Description
`list_sites`	List all registered sites with their IDs

Page views

Tool	Description
`get_stats`	Total pageviews, visitors, visits and bounces
`get_pageviews_series`	Daily pageviews and visitors over a date range
`get_pageviews_by_hour`	Pageviews by hour of day (0-23)
`get_top_pages`	Most visited URLs
`get_top_pages_expanded`	Top pages with engagement metrics
`get_top_titles`	Top page titles
`get_entry_pages`	Most common landing pages
`get_exit_pages`	Most common exit pages
`get_top_referrers`	Top referrers
`get_top_referrers_expanded`	Top referrers with engagement metrics
`get_browsers`	Browser breakdown
`get_operating_systems`	OS breakdown
`get_devices`	Device type breakdown
`get_languages`	Language breakdown
`get_time_zones`	Time zone breakdown
`get_utm_sources`	UTM source breakdown
`get_utm_mediums`	UTM medium breakdown
`get_utm_campaigns`	UTM campaign breakdown
`get_utm_contents`	UTM content breakdown
`get_utm_terms`	UTM term breakdown

Custom events

Tool	Description
`get_top_events`	Custom event names ranked by count
`get_event_series`	Daily event counts over a date range

Web Vitals

Tool	Description
`get_web_vitals_summary`	Average, p75 and p90 per metric (CLS, FCP, INP, LCP, TTFB)
`get_web_vitals_by_page`	Per-page breakdown for a specific metric
`get_web_vitals_distribution`	Good/needs improvement/poor counts per metric

Configuration

Variable	Required	Description
`YAWA_SESSION_SECRET`	Recommended	Secret used to hash session IDs. If not set, random UUIDs are used instead (less accurate visitor counting).
`YAWA_DATA_DIR`	No	Path where the DuckDB database file is stored. Defaults to `/data`. If modified, update the volume mount in your `docker-compose.yml` accordingly.

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

Name		Name	Last commit message	Last commit date
Latest commit History 86 Commits
.github		.github
packages		packages
.dockerignore		.dockerignore
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
Dockerfile.app		Dockerfile.app
LICENSE		LICENSE
README.md		README.md
build.compress.ts		build.compress.ts
bun.lock		bun.lock
bunfig.toml		bunfig.toml
docker-compose.dev.yml		docker-compose.dev.yml
package.json		package.json
test-setup.ts		test-setup.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

yawa - Yet Another Web Analytics

Motivation

How it works

Quick Start

Create an access token

Register your site

Connect your MCP client

Claude Code

Claude (web)

Codex

Mistral (Vibe)

Cursor

Install the tracker

Script tag

npm

Custom events

Web Vitals

API

Options

MCP tools

Sites

Page views

Custom events

Web Vitals

Configuration

Development

Setup

Run locally

CLI

Run tests

Build

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 20

Contributors

Uh oh!

Languages