Clicky MCP Server

Сервер Model Context Protocol (MCP), который предоставляет Clicky веб-аналитику в виде 11 инструментов для ИИ-ассистентов — количество посетителей, популярные страницы, источники трафика, показатель отказов, поисковые запросы, посетители в реальном времени и многое другое. См. Справочник инструментов для получения полного списка.

Быстрый старт

Вам потребуется:

• Установленный Node.js 20+ (node --version)

• Clicky Site ID и Site Key — их можно найти на странице https://clicky.com/user/preferences/site в разделе "Info"

• Клонированный и собранный репозиторий:

  git clone https://github.com/colintoh/clicky-mcp.git
  cd clicky-mcp && npm install && npm run build

Затем выберите ваш MCP-хост ниже.

Почему нет шага npm start? MCP-серверы stdio не работают как автономные демоны — ваш MCP-хост (Claude Desktop, Claude Code и т. д.) запускает сервер как подпроцесс по требованию и взаимодействует с ним через stdin/stdout. Вам не нужно ничего «запускать» самостоятельно.

Claude Desktop

1. Откройте файл конфигурации (создайте его, если он отсутствует):

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Добавьте это в блок mcpServers файла (замените три заполнителя ALL_CAPS):

   {
     "mcpServers": {
       "clicky-analytics": {
         "command": "ABSOLUTE_PATH_TO_NODE", // e.g. /Users/.../.nvm/versions/node/v25.2.1/bin/node
         "args": ["ABSOLUTE_PATH_TO_CLICKY_MCP_FOLDER/dist/index.js"], // e.g. /Users/.../clicky-mcp/dist/index.js
         "env": {
           "CLICKY_SITE_ID": "YOUR_SITE_ID",
           "CLICKY_SITE_KEY": "YOUR_SITE_KEY"
         }
       }
     }
   }

   Получите ABSOLUTE_PATH_TO_NODE, выполнив which node в терминале. Не просто пишите "node" — Claude Desktop запускается через launchd с минимальным PATH, который не включает nvm или homebrew, поэтому простое "node" не сработает без уведомлений. То же самое касается пути к dist/index.js: он должен быть абсолютным.

3. Полностью завершите работу Claude Desktop (⌘Q на macOS — закрытия окна недостаточно), затем откройте его снова.

4. Проверьте, спросив у Claude: "list my Clicky MCP tools" — вы должны увидеть 11 инструментов.

Если что-то пошло не так, см. Устранение неполадок.

Claude Code

Одна команда:

claude mcp add clicky-analytics \
  -e CLICKY_SITE_ID=YOUR_SITE_ID \
  -e CLICKY_SITE_KEY=YOUR_SITE_KEY \
  -- node /absolute/path/to/clicky-mcp/dist/index.js

По умолчанию это записывается в ~/.claude.json. Добавьте --scope project, чтобы записать файл .mcp.json локально для проекта. Перезапустите Claude Code (или выполните /mcp для обновления), и 11 инструментов станут доступны.

MCP Inspector (отладка)

Используйте это, если хотите вызывать инструменты напрямую, не подключая сервер к хосту — удобно для проверки схем или отладки ответов:

npx @modelcontextprotocol/inspector node dist/index.js

Затем откройте полученный URL, установите CLICKY_SITE_ID и CLICKY_SITE_KEY в качестве переменных окружения в интерфейсе Inspector (или передайте --site-id … --site-key … в качестве аргументов CLI после dist/index.js) и начните работу.

Related MCP server: Plausible MCP Server

Параметры даты

Каждый инструмент, работающий с датами, принимает либо явный диапазон дат, либо ключевое слово относительной даты Clicky — но не оба сразу:

• Явный диапазон: start_date + end_date, оба в формате YYYY-MM-DD, диапазон ≤ 31 дня.

• Ключевое слово: date_range, одно из: today, yesterday, last-7-days, last-30-days, this-week, last-week, this-month, last-month, this-year, last-year.

Пример:

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

Справочник инструментов

Все 11 инструментов, отсортированы примерно по алфавиту в зависимости от варианта использования.

get_total_visitors

Общее количество посетителей за период.

• start_date / end_date или date_range

get_actions

Общее количество просмотров страниц/действий за период.

• start_date / end_date или date_range

• limit (число, необязательно, макс. 1000)

get_bounce_rate

Показатель отказов и среднее время на сайте за период.

• start_date / end_date или date_range

get_visitors_online

Количество посетителей в реальном времени и сегментация. Не принимает параметров.

get_top_pages

Самые популярные страницы за период.

• start_date / end_date или date_range

• limit (число, необязательно, макс. 1000)

get_page_traffic

Данные о трафике для конкретного URL страницы.

• url (строка, обязательно)

• start_date / end_date или date_range

get_traffic_sources

Разбивка источников трафика — с возможностью фильтрации по URL страницы.

• start_date / end_date или date_range

• page_url (строка, необязательно) — полный URL или путь

get_referring_domains

Топ доменов-рефереров, направляющих трафик.

• start_date / end_date или date_range

• limit (число, необязательно, макс. 1000)

get_domain_visitors

Данные о посетителях, отфильтрованные по домену-рефереру, с дополнительной сегментацией.

• domain (строка, обязательно)

• start_date / end_date или date_range

• segments (массив, необязательно) — ["pages", "visitors"]. По умолчанию ["visitors"].

• limit (число, необязательно, макс. 1000)

get_searches

Топ поисковых запросов, по которым пришли посетители.

• start_date / end_date или date_range

• limit (число, необязательно, макс. 1000)

get_countries

Разбивка посетителей по странам.

• start_date / end_date или date_range

• limit (число, необязательно, макс. 1000)

Ограничения API

Установлены Clicky, а не этим сервером:

• Максимальный явный диапазон дат: 31 день

• Максимальное количество результатов на запрос: 1000 элементов

• Один одновременный запрос с одного IP для одного ID сайта

Устранение неполадок

"Claude Desktop не видит сервер." Проверьте лог запуска по адресу ~/Library/Logs/Claude/mcp-server-clicky-analytics.log. Самая частая причина — node отсутствует в PATH launchd для Claude Desktop — исправьте это, заменив "command": "node" на абсолютный путь из which node. Вторая по частоте причина — забыли полностью завершить работу Claude Desktop (⌘Q, а не просто закрыть окно).

"Date range cannot exceed 31 days." Это ограничение API Clicky, а не наше. Либо сузьте диапазон, либо используйте ключевое слово date_range, например last-30-days.

Локальная разработка

Для работы над сервером, а не просто его использования.

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)

Для локальной разработки учетные данные можно взять из файла .env в корне проекта:

CLICKY_SITE_ID=your_site_id
CLICKY_SITE_KEY=your_site_key

Файл .env игнорируется git. Не используйте .env для хостов вроде Claude Desktop — передавайте учетные данные через блок env в конфигурации хоста, как показано в разделе Быстрый старт. Сервер загружает .env только в том случае, если учетные данные еще не заданы в переменных окружения.

Git-хук pre-push в .githooks/pre-push автоматически запускает npm test перед любой отправкой (push), которая обновляет удаленную ветку main, поэтому регрессия не останется незамеченной. Он устанавливается автоматически скриптом prepare npm после npm install. Отправки в ветки функций не ограничены. В экстренном случае можно обойти проверку с помощью git push --no-verify.

Структура проекта

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

Установка этого MCP через ИИ-агента

Если вы хотите, чтобы ИИ-агент (например, Claude Code в другом проекте) установил этот MCP за вас, укажите ему на этот раздел. Агент должен:

1. Клонировать и собрать:

   git clone https://github.com/colintoh/clicky-mcp.git
   cd clicky-mcp && npm install && npm run build

2. Запросить у пользователя Clicky Site ID и Site Key (https://clicky.com/user/preferences/site).

3. Выполнить which node и получить абсолютный путь.

4. Найти конфигурацию Claude Desktop пользователя (пути в разделе Быстрый старт › Claude Desktop) и объединить фрагмент mcpServers из этого раздела, подставив абсолютный путь к node, абсолютный путь к dist/index.js и учетные данные пользователя.

5. Попросить пользователя полностью перезапустить Claude Desktop (⌘Q), затем проверить, спросив у Claude: "list my Clicky MCP tools" — должны появиться 11 инструментов.

Для Claude Code одна команда claude mcp add в разделе Быстрый старт › Claude Code быстрее и записывает конфигурацию за один шаг.

Лицензия

MIT