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.

"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?"

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

How it works

Yet another web analytics has three moving parts.

Your app or website sends analytics with a lightweight JavaScript library (yawa) 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/Web, Codex, or any MCP-compatible client) to your endpoint and query your data in natural language.

Related MCP server: Gizmo Analytics

Quick Start

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

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:

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"

Cursor

Add to your mcp.json:

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

Claude (web)

Go to Settings -> Integrations -> Add MCP server and enter your server URL and Bearer token.

Once connected, start by listing your sites:

List my analytics sites
Show me stats for yourdomain.com for the last 30 days
What are my top pages this week?

Install the tracker

Install the tracker in your website or frontend app:

npm install yawa

Setup

import { initYawa } from "yawa";

const cleanup = initYawa({
  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 trackEvent with a name and optional metadata:

import { trackEvent } from "yawa";

trackEvent({ 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 { initYawa } from "yawa";

const cleanup = initYawa({
  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