traffic-report

Files (1)

• SKILL.md

SKILL.md (first lines)

# Traffic Report

Generate a comprehensive traffic report for a Matomo-tracked site. Default period is last 7 days unless specified in $ARGUMENTS.

## Site selection

If $ARGUMENTS contains a site ID or name, use that. If the conversation already has a site in context, use that. Otherwise, call `matomo_list_sites`, present a short numbered list (ID, name, URL), and ask which site to analyze. Do not proceed until a site is selected.

## Steps

1. **Visits summary** using `matomo_get_visits` for the requested period

2. **Real-time snapshot** using `matomo_get_live_counters` (last 30 minutes)

3. **Top pages** using `matomo_get_top_pages` with limit 10

4. **Entry pages** using `matomo_get_entry_pages` with limit 5 to show where visitors land

5. **Traffic sources** using `matomo_get_search_engines` and `matomo_get_ai_assistants` with limit 5 each

6. **Device segment** using `matomo_get_devices` for the same period to show the desktop vs mobile split. If the user asked for a mobile-only report, pass `device: "mobile"` to steps 1, 3, 4 instead and note that the whole report is scoped to smartphone+tablet+phablet.

7. **Present as a report** with sections:
   - Key metrics: visits, unique visitors, actions, bounce rate, avg time on site
   - Currently online (live counters)
   - Top pages (table: page, visits, avg time, bounce rate)
   - Where visitors come from (search engines, AI assistants)
   - Top landing pages
   - Device split (desktop vs mobile share)

Keep the report concise and highlight anything unusual (high bounce rates, traffic spikes, etc.).

## Fallback when segments return zero

If a `device`-filtered call comes back with all-zero metrics while the same
query without `device` returns normal numbers, the Matomo server is refusing
to aggregate the segment for this API token (it lacks `process_new_segment`
or the segment isn't pre-archived). Do not claim "no mobile traffic" — that's
almost never the real answer.

Try these in order:

1. **Switch to `matomo_count_visits_by_segment`.** It uses the Live API
   under the hood and does NOT need segment archiving. For mobile:
   `{siteId, period, date, device: "mobile"}` returns
   `{visits, byDevice, byCountryTop10}`.
2. **Check `matomo_list_segments`** to find saved segments on the instance.
   Any segment with `auto_archive=1` is pre-archived and will always return
   real numbers when you reference its `definition` string in `segment`.
3. **Open the Matomo UI in a logged-in browser session** as a last resort
   — the UI uses the user's permissions, not the token:
   ```
   <matomo-host>/index.php?module=CoreHome&action=index
     &idSite=<id>&period=<period>&date=<date>
     &segment=deviceType%3D%3Dsmartphone%2CdeviceType%3D%3Dtablet%2CdeviceType%3D%3Dphablet
   ```
4. **Longer-term fix**: ask the Matomo admin to grant
   `process_new_segment` on the token or pre-archive common segments.

From lucaspretti/matomo-mcp-client, MIT.

More from lucaspretti/matomo-mcp-client