Clics

Clics

Clics is privacy-friendly, cookieless web analytics. Agents manage projects, goals, funnels, and analytics stats in two ways:

• MCP tools (clics server via @clicsdev/mcp) — preferred for agents.
• CLI (@clicsdev/cli, binary clics) — fallback when MCP is unavailable, for manual verification, or for scripts and CI.

Choosing MCP vs CLI

Prefer MCP tools whenever the clics MCP server is connected — no shell is required, and the API key is supplied by the MCP client environment.

Use the CLI when:

• The MCP server is not connected in this session.
• You need to verify behavior manually or from a script or terminal.
• You are automating in CI where stdio MCP is not available.

Authentication

MCP — set in the MCP client config (never pass the API key as a tool argument):

CLICS_API_KEY=your_api_key

Typical Cursor setup: npx -y @clicsdev/mcp with that environment variable.

CLI — one-time local configuration (stored in ~/.config/clics/):

npm install -g @clicsdev/cli
# or: npx @clicsdev/cli …
clics init --api-key ""

Re-run clics init to rotate the key. Successful CLI commands print a single JSON document on stdout; errors are written to stderr with a non-zero exit code.

MCP tools (preferred)

Server name: clics. Call tools directly; full input schemas are defined on each tool.

Projects

| Tool | Key inputs | |------|------------| | list_projects | optional cursor, limit | | get_project | project_id | | create_project | name, website_url, optional allow_localhost | | update_project | project_id, optional name, website_url, allow_localhost | | delete_project | project_id |

Goals

env_id: production \| development (default production).

| Tool | Key inputs | |------|------------| | list_goals | project_id, optional env_id | | create_goal | project_id, goal_type (page\|event), display_name, optional env_id, page_path, event_name | | update_goal | goal_id, goal_type, display_name, optional page_path, event_name | | delete_goal | goal_id |

Funnels

| Tool | Key inputs | |------|------------| | list_funnels | project_id, optional env_id, cursor, limit | | get_funnel | funnel_id | | create_funnel | project_id + body (name, conversion_window, steps, optional env_id) | | update_funnel | funnel_id + body without env_id | | delete_funnel | funnel_id |

Stats

| Tool | Key inputs | |------|------------| | query_stats | full Stats body: project_id, metrics, date_range, optional domain, dimensions, filters, order_by, include, pagination |

MCP example (query_stats input):

{
  "project_id": "your_project_id",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "last30days",
  "include": { "previous_period": true }
}

Responses return JSON text in content and the same object in structuredContent. Failures set isError: true.

CLI reference (fallback)

Package: @clicsdev/cli. Binary: clics. Help: clics --help, clics --version, clics help .

Run without a global install: npx @clicsdev/cli ….

Projects

List

clics projects list
clics projects list --limit 20
clics projects list --cursor ""

Get

clics projects get 

Create

clics projects create --name "My site" --website-url https://example.com
clics projects create --name "My site" --website-url https://example.com --allow-localhost

Update

clics projects update  --name "New name"
clics projects update  --website-url https://new.example.com
clics projects update  --allow-localhost

Delete

clics projects delete 

Goals

env_id is production or development (API default: production).

List

clics goals list 
clics goals list  --env-id development

Create — page goal:

clics goals create  --goal-type page --display-name "Signup page" --page-path /signup

Create — event goal:

clics goals create  --goal-type event --display-name "Purchase" --event-name purchase

Optional environment:

clics goals create  --goal-type page --display-name "Home" --page-path / --env-id development

Update

clics goals update  --goal-type page --display-name "Signup" --page-path /signup
clics goals update  --goal-type event --display-name "Purchase" --event-name purchase

Delete

clics goals delete 

Funnels

List, get, and delete use flags. Create and update take JSON via --body (inline or @file.json).

List

clics funnels list 
clics funnels list  --env-id production --limit 20
clics funnels list  --cursor ""

Get

clics funnels get 

Create

clics funnels create  --body @funnel.json

Example funnel.json:

{
  "name": "Signup funnel",
  "conversion_window": { "value": 7, "unit": "days" },
  "steps": [
    {
      "name": "Landing",
      "filters": [{ "filter_type": "page", "operator": "is", "values": ["/"] }]
    },
    {
      "name": "Signup",
      "filters": [{ "filter_type": "page", "operator": "is", "values": ["/signup"] }]
    }
  ]
}

Optional env_id in the body: production | development.

Update (same shape as create, without env_id):

clics funnels update  --body @funnel-update.json

Delete

clics funnels delete 

Query analytics

--metrics and --date-range are required (unless using --file).

Presets

clics query  --metrics visitors --date-range last24h
clics query  --metrics visitors --date-range last7days
clics query  --metrics visitors --date-range last30days
clics query  --metrics visitors --date-range last3months
clics query  --metrics visitors --date-range last12months
clics query  --metrics visitors --date-range monthToDate
clics query  --metrics visitors --date-range quarterToDate
clics query  --metrics visitors --date-range yearToDate
clics query  --metrics visitors --date-range allTime

Basic KPIs

clics query  --metrics visitors pageviews bounce_rate --date-range last30days

Comparison / totals

clics query  --metrics visitors pageviews bounce_rate --date-range last30days --previous-period --total-rows

Domain filter

clics query  --metrics visitors --date-range last7days --domain example.com

Use --domain localhost for development traffic only.

Breakdown

clics query  --metrics visitors pageviews --date-range last30days --dimensions visit:country

Pagination

clics query  --metrics visitors --date-range last30days --dimensions visit:country --limit 50 --offset 0

Advanced file (filters, order_by, custom date ranges):

clics query  --file query.json

Example query.json:

{
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "last30days",
  "dimensions": ["visit:country"],
  "filters": [["is", "visit:country", ["US", "FR"]]],
  "order_by": [["visitors", "desc"]],
  "include": {
    "previous_period": true,
    "total_rows": true
  },
  "pagination": {
    "limit": 50,
    "offset": 0
  }
}

project_id in the file is overwritten by the CLI argument.

Allowed metrics: visitors · visits · pageviews · bounce_rate · visit_duration · views_per_visit · conversion_rate · events

• KPI / time-series: visitors, visits, pageviews, bounce_rate, visit_duration, views_per_visit
• Breakdown: visitors, pageviews, conversion_rate, events

Allowed date ranges: last24h · last7days · last30days · last3months · last12months · monthToDate · quarterToDate · yearToDate · allTime (custom ISO pairs via --file)

Allowed dimensions: event:page · event:hostname · visit:country · visit:device · visit:browser · visit:os · visit:referrer · visit:utm_source · visit:utm_medium · visit:utm_campaign · visit:utm_term · visit:utm_content · time · time:hour · time:day

Scripting

clics projects list | jq '.projects[].id'

Prefer --body @file.json / --file file.json over inline JSON (especially on PowerShell).

Playbooks

1. Overview (last 30 days)

1. Run list_projects or clics projects list and pick a project_id.
2. Run query_stats or clics query --metrics visitors visits pageviews bounce_rate visit_duration views_per_visit --date-range last30days --previous-period.
3. Summarize KPIs and period-over-period changes from the JSON response.

2. Top pages and countries

1. Resolve project_id as above.
2. Pages: query_stats with metrics: ["visitors","pageviews"], date_range: "last30days", dimensions: ["event:page"], order_by: [["visitors","desc"]], pagination: { "limit": 10 }.

CLI: clics query --metrics visitors pageviews --date-range last30days --dimensions event:page --limit 10

1. Countries: same query with dimensions: ["visit:country"].

CLI: clics query --metrics visitors pageviews --date-range last30days --dimensions visit:country --limit 10

3. Goals and funnels check

1. Run list_goals or clics goals list (add --env-id development if needed).
2. Run list_funnels or clics funnels list .
3. Optionally run get_funnel or clics funnels get for step details.
4. Report what is configured. Do not create or delete resources unless the user asked.

Manual verification

Confirm authentication and API access with the CLI so JSON is visible in the terminal:

clics projects list
clics query  --metrics visitors --date-range last7days

Expect a JSON projects payload and a stats results array. Common errors:

• API key is required. Run clics init. — run clics init --api-key "…"
• 401 / invalid key — rotate or recreate the key, then run clics init again
• 403 / UPGRADE_REQUIRED — a paid plan is required for API access

Links

• Product: https://clics.dev
• Dashboard: https://platform.clics.dev
• Docs: https://clics.dev/docs
• MCP: @clicsdev/mcp
• CLI: @clicsdev/cli

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: P-Essonam
• Source: P-Essonam/clicsdev
• License: MIT
• Homepage: https://clics.dev

Install and usage instructions live in the source repository linked above.