Clicky MCP Server

A Model Context Protocol (MCP) server that exposes Clicky web analytics as 12 tools for AI assistants — visitor counts, top pages, traffic sources, campaigns, bounce rate, search terms, real-time visitors, and more. See the Tool reference for the full list.

Quick start

You need:

• Node.js 20+ installed (node --version)

• A Clicky Site ID and Site Key — find both at https://clicky.com/user/preferences/site under "Info" (you'll paste these into a local .env file, never into the chat)

• An MCP-capable AI agent — Claude Code, Claude Desktop, Codex, opencode, Cursor, Cline, …

MCP servers are installed by your agent, not started by hand — so the fastest setup is to hand the job over. Copy the block below and paste it to your agent:

Install the Clicky MCP server for me. It's a stdio MCP server, so the same definition works in any MCP host (Claude Code, Claude Desktop, Codex, opencode, Cursor, Cline, …) — register it using your host's own mechanism; only the config format differs, and you know your host better than this doc does.

1. Clone and build:
     git clone https://github.com/colintoh/clicky-mcp.git
     cd clicky-mcp && npm install && npm run build
   Confirm the build produced dist/index.js. If it's missing, stop and show me
   the build output instead of continuing.

2. Set up credentials WITHOUT putting them in this chat:
     cp .env.example .env
   Then tell me to open clicky-mcp/.env in my editor and paste my Clicky Site ID
   and Site Key there myself (from https://clicky.com/user/preferences/site,
   under "Info"). Do NOT ask me to paste the keys here, and do NOT read or print
   .env — the server loads it at startup; the keys must never enter this chat.

3. Register it with this stdio server definition (no credentials in the host
   config — the server reads them from .env):
     command:   absolute path to node — run `which node`; a bare "node" or a
                relative path will fail
     args:      ["<absolute-path>/clicky-mcp/dist/index.js"]
     transport: stdio
   Add it with your host's own mechanism. One-line references if helpful:
     - Claude Code: `claude mcp add clicky-analytics -- <node> <path>/clicky-mcp/dist/index.js`
     - JSON hosts (Claude Desktop, Cursor, Cline, …): a "clicky-analytics"
       entry under "mcpServers" with command + args (no env block needed)
     - Codex (~/.codex/config.toml): [mcp_servers.clicky-analytics] with the
       same command + args
   If the host needs a restart to load new servers (Claude Desktop needs a full
   Cmd-Q quit, not just closing the window), tell me to do that.

4. Verify: confirm your host lists a "clicky-analytics" server exposing 12 tools.

Why no npm start? MCP stdio servers aren't standalone daemons — your agent's MCP host spawns the server as a subprocess on demand and talks to it over stdin/stdout. There's nothing to "start" yourself, which is also why setup is "tell your agent" rather than "run a command."

Related MCP server: Plausible MCP Server

Date parameters

Every date-aware tool accepts either an explicit date range or a Clicky relative-date keyword — but not both:

• Explicit: start_date + end_date, both YYYY-MM-DD, range ≤ 31 days.

• Keyword: date_range, one of today, yesterday, last-7-days, last-30-days, this-week, last-week, this-month, last-month, this-year, last-year.

Example:

{ "date_range": "last-7-days" }

Tool reference

All 12 tools, alphabetical-ish by use case.

get_total_visitors

Total visitor counts for a period.

• start_date / end_date or date_range

get_actions

Total pageviews/actions for a period.

• start_date / end_date or date_range

• limit (number, optional, max 1000)

get_bounce_rate

Bounce rate and average time-on-site for a period.

• start_date / end_date or date_range

get_visitors_online

Real-time visitor count and segmentation. Takes no parameters.

get_top_pages

Most popular pages for a period.

• start_date / end_date or date_range

• limit (number, optional, max 1000)

get_page_traffic

Traffic data for a specific page URL.

• url (string, required)

• start_date / end_date or date_range

get_traffic_sources

Traffic sources breakdown — optionally filter by page URL.

• start_date / end_date or date_range

• page_url (string, optional) — full URL or path

get_referring_domains

Top referring domains sending traffic.

• start_date / end_date or date_range

• limit (number, optional, max 1000)

get_campaigns

Traffic grouped by campaign tag (utm_campaign or Clicky campaign tracking). Only tagged inbound traffic appears here — untagged organic/direct traffic does not.

• start_date / end_date or date_range

• limit (number, optional, max 1000)

• include_keywords (boolean, optional) — also return campaign keyword/term tags

get_domain_visitors

Visitor data filtered by referrer domain, with optional segmentation.

• domain (string, required)

• start_date / end_date or date_range

• segments (array, optional) — ["pages", "visitors"]. Defaults to ["visitors"].

• limit (number, optional, max 1000)

get_searches

Top search terms that brought visitors.

• start_date / end_date or date_range

• limit (number, optional, max 1000)

get_countries

Visitor breakdown by country.

• start_date / end_date or date_range

• limit (number, optional, max 1000)

API limits

Imposed by Clicky, not by this server:

• Maximum explicit date range: 31 days

• Maximum results per request: 1,000 items

• One simultaneous request per IP per site ID

Troubleshooting

"Claude Desktop doesn't see the server." Check the spawn log at ~/Library/Logs/Claude/mcp-server-clicky-analytics.log. The most common cause is node not being on Claude Desktop's launchd PATH — fix by replacing "command": "node" with the absolute path from which node. The second-most-common cause is forgetting to fully quit Claude Desktop (⌘Q, not just close the window).

"Date range cannot exceed 31 days." That's a Clicky API limit, not us. Either narrow the range or use a date_range keyword like last-30-days.

Local development

For working on the server, not just using it.

npm install         # install deps
npm run dev         # run with tsx, watching for changes (used for local testing only)
npm run build       # compile TS to dist/
npm test            # 46 unit tests, offline, no credentials needed
npm run test:integration  # live API smoke test (requires .env or env vars)

Credentials come from a .env file in the project root — copy the template and fill in your values:

cp .env.example .env

CLICKY_SITE_ID=your_site_id
CLICKY_SITE_KEY=your_site_key

.env is gitignored, and it's the recommended way to supply credentials for both local dev and MCP hosts: it keeps your keys out of host config files and out of any agent chat. The server resolves .env relative to its own location, so it's found no matter what working directory the host launches it from, and it only loads .env when the credentials aren't already in the environment. You can still pass CLICKY_SITE_ID/CLICKY_SITE_KEY via the host's env block or --site-id/--site-key args if you prefer.

A pre-push git hook in .githooks/pre-push auto-runs npm test before any push that updates the remote main branch, so a regression can't slip out unnoticed. It's installed automatically by the prepare npm script after npm install. Pushes to feature branches are not gated. Bypass in an emergency with git push --no-verify.

Project structure

clicky-mcp/
├── src/
│   ├── index.ts              # MCP server + tool dispatcher
│   ├── clicky-client.ts      # Clicky HTTP API client
│   ├── date-utils.ts         # Shared date param builder
│   └── tools/                # One file per tool
├── test/                     # node:test unit tests
├── scripts/verify.mjs        # Live API smoke runner
├── .githooks/pre-push        # Auto-installed test gate for main
├── package.json
├── tsconfig.json
└── README.md

License

MIT