@clicsdev/mcp

Privacy-friendly analytics for AI agents, made by Clics.

Local Model Context Protocol server for cookie-free web analytics — manage projects, goals, funnels, sessions, AI crawlers, and query stats from Cursor, VS Code, Windsurf, Antigravity, OpenCode, Codex, Claude Desktop, Claude Code, or any MCP client.

Install

npm install -g @clicsdev/mcp

Or run without a global install via npx (see config below).

Authenticate

Create an API key in the Clics dashboard, then set it in your MCP client environment:

CLICS_API_KEY=your_api_key

The server talks to https://api.clics.dev.

Clients

Replace your_api_key with your Clics API key. Prefer npx so you always get the latest published package; use "command": "clics-mcp" instead if you installed globally with npm install -g @clicsdev/mcp.

Cursor

File: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).

{
  "mcpServers": {
    "clics": {
      "command": "npx",
      "args": ["-y", "@clicsdev/mcp"],
      "env": {
        "CLICS_API_KEY": "your_api_key"
      }
    }
  }
}

VS Code

File: .vscode/mcp.json (workspace) or user MCP config (MCP: Open User Configuration).

VS Code uses the root key servers (not mcpServers):

{
  "servers": {
    "clics": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@clicsdev/mcp"],
      "env": {
        "CLICS_API_KEY": "your_api_key"
      }
    }
  }
}

Windsurf

File: ~/.codeium/windsurf/mcp_config.json (global only).

{
  "mcpServers": {
    "clics": {
      "command": "npx",
      "args": ["-y", "@clicsdev/mcp"],
      "env": {
        "CLICS_API_KEY": "your_api_key"
      }
    }
  }
}

Antigravity

File: ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace).

In the IDE: Agent panel → ... → MCP Servers → Manage MCP Servers → View raw config.

{
  "mcpServers": {
    "clics": {
      "command": "npx",
      "args": ["-y", "@clicsdev/mcp"],
      "env": {
        "CLICS_API_KEY": "your_api_key"
      }
    }
  }
}

OpenCode

File: opencode.json or opencode.jsonc (project or global OpenCode config).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clics": {
      "type": "local",
      "command": ["npx", "-y", "@clicsdev/mcp"],
      "enabled": true,
      "environment": {
        "CLICS_API_KEY": "your_api_key"
      }
    }
  }
}

Codex

File: ~/.codex/config.toml (global) or .codex/config.toml (trusted project).

Or via CLI:

codex mcp add clics --env CLICS_API_KEY=your_api_key -- npx -y @clicsdev/mcp

[mcp_servers.clics]
command = "npx"
args = [
  "-y",
  "@clicsdev/mcp",
]

[mcp_servers.clics.env]
CLICS_API_KEY = "your_api_key"

Claude Desktop

File: claude_desktop_config.json — not the same as Claude Code.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

In the app: Settings → Developer → Edit Config. Fully quit and reopen Claude Desktop after saving.

{
  "mcpServers": {
    "clics": {
      "command": "npx",
      "args": ["-y", "@clicsdev/mcp"],
      "env": {
        "CLICS_API_KEY": "your_api_key"
      }
    }
  }
}

Claude Code

File: .mcp.json (project, shareable) or ~/.claude.json under top-level mcpServers (user scope).

Or via CLI:

claude mcp add clics --scope user --env CLICS_API_KEY=your_api_key -- npx -y @clicsdev/mcp

{
  "mcpServers": {
    "clics": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@clicsdev/mcp"],
      "env": {
        "CLICS_API_KEY": "your_api_key"
      }
    }
  }
}

Tools

Projects

• 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

• list_goals — project_id, optional env_id (production | development)
• get_goal — goal_id; returns the type-specific goal rule
• get_goal_stats — goal_id, optional domain, date_range (default last7days), start, end, timezone, referrer_ai_provider; returns dashboard-ready totals, comparison, and time series
• create_goal — project_id, goal_type, display_name, rule, optional env_id
• update_goal — goal_id, optional goal_type, display_name, rule
• delete_goal — goal_id

goal_type is one of page, event, outbound, or scroll_depth. The rule must match its type: { "page_path": "/pricing" }, { "event_name": "purchase" }, { "outbound_url": "https://partner.example.com/signup" }, or { "page_path": "/pricing", "scroll_depth_threshold": 75 }. Scroll depth is a whole percentage from 1 to 100.

Funnels

• list_funnels — project_id, optional env_id, cursor, limit
• get_funnel — funnel_id
• get_funnel_stats — funnel_id, optional domain, date_range (default last7days), start, end, timezone, referrer_ai_provider; returns dashboard-ready step counts, conversion, drop-off, and timing
• create_funnel — project_id plus funnel body (name, conversion_window, steps, optional env_id)
• update_funnel — funnel_id plus funnel body without env_id
• delete_funnel — funnel_id

Sessions

• list_session_filter_values — project_id, field, optional domain, period, timezone, limit; field is country, device, browser, os, page_entry, page_exit, or referrer
• list_sessions — project_id, optional domain, date_range (default last7days), start, end, timezone, cursor, limit
• get_session — project_id, session_id, optional domain, date_range (default allTime), start, end, timezone
• list_session_events — project_id, session_id, optional domain, date_range (default allTime), start, end, timezone

AI crawlers

• get_ai_crawler_analytics — project_id, optional date_range (default last7days), start, end, timezone, category, provider, provider_op, crawler, crawler_op, status, status_op, breakdown_limit, filter_values_limit

AI crawler analytics always query production. category is answer_fetch, search_index, or training. provider and crawler are enum values from the supported crawler registry. Filter operators are is or is_not.

Providers: OpenAI, Anthropic, Perplexity, Google, Microsoft, Mistral, Amazon, DuckDuckGo, Apple, Moonshot AI, Common Crawl.

Crawlers: ChatGPT-User, OAI-SearchBot, GPTBot, Claude-User, Claude-SearchBot, ClaudeBot, Perplexity-User, PerplexityBot, Google-Agent, Google-GeminiNotebook, Google-NotebookLM, Google-Read-Aloud, Google-InspectionTool, Googlebot, GoogleOther, Google-CloudVertexBot, Bingbot, msnbot, MistralAI-User, MistralAI-Index, Amzn-User, Amzn-SearchBot, Amazonbot, DuckAssistBot, Applebot, Kimi-User, Kimi-SearchBot, KimiBot, CCBot.

Analytics stats

• query_stats — full Stats API body: project_id, metrics, date_range, optional domain, timezone, dimensions, filters, include, order_by, pagination

Allowed dimensions are event:page, event:hostname, event:name, event:outbound_url, visit:country, visit:device, visit:browser, visit:os, visit:referrer, referrer:ai_provider, visit:utm_source, visit:utm_medium, visit:utm_campaign, visit:utm_term, visit:utm_content, time, time:hour, and time:day.

For get_goal_stats, get_funnel_stats, session tools, and query_stats, timezone is an IANA timezone and defaults to UTC. referrer_ai_provider accepts chatgpt, claude, gemini, perplexity, or copilot.

For get_goal_stats and get_funnel_stats, date_range is one of last24h, last7days, last30days, last3months, last12months, monthToDate, quarterToDate, yearToDate, or allTime. Pass both start and end for a custom range.

Example query_stats input:

{
  "project_id": "your_project_id",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "last30days",
  "timezone": "Europe/London",
  "include": {
    "previous_period": true,
    "total_rows": true
  }
}

For a KPI query without dimensions, include.previous_period: true adds a comparison object to the result:

{
  "comparison": {
    "previous_metric_values": { "visitors": 120, "pageviews": 340 },
    "change_percent": { "visitors": 12.5, "pageviews": -4.2 }
  }
}

comparison is omitted for breakdowns and time-series queries.

Responses

Each tool returns JSON text in content and the same object in structuredContent. Errors are returned as MCP tool errors (isError: true).

Links

• Clics
• Dashboard
• Documentation
• CLI