# Clicky MCP Server

A Model Context Protocol (MCP) server that exposes [Clicky](https://clicky.com) 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](#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."

---

## 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:

```json
{ "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.

```bash
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:

```bash
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