Getting Started

Yet Another Web Analytics (yawa) is a self-hosted web analytics platform with no UI. This guide walks you through deploying the server, registering your first site, and connecting an MCP client.

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.
Terminal window
```
echo "YAWA_SESSION_SECRET=$(openssl rand -base64 32)" > .env
```
Start the server
Terminal window
```
docker compose up -d
```
Create an access token
Terminal window
```
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

Install the tracker

Install the tracker in your website or frontend app:
Terminal window
```
npm install yawa-tracker
```
Then initialize it:
```
import { init } from "yawa-tracker";

const cleanup = init({
  serverUrl: "https://your-yawa-server.com",
});
```
Deploy or run your site and generate few page views.

Connect your MCP client

Connect for example Claude Code using the token created above:

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

Then start asking questions :)

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