Servidor MCP de Clicky

Un servidor del Protocolo de Contexto de Modelos (MCP) que expone los análisis web de Clicky como 11 herramientas para asistentes de IA: recuentos de visitantes, páginas principales, fuentes de tráfico, tasa de rebote, términos de búsqueda, visitantes en tiempo real y más. Consulta la Referencia de herramientas para ver la lista completa.

Inicio rápido

Necesitas:

Node.js 20+ instalado (node --version)
Un ID de sitio y una clave de sitio de Clicky: encuéntralos en https://clicky.com/user/preferences/site bajo "Info"

Este repositorio clonado y compilado una vez:

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

Luego elige tu host MCP a continuación.

¿Por qué no hay un paso npm start? Los servidores stdio de MCP no se ejecutan como demonios independientes; tu host MCP (Claude Desktop, Claude Code, etc.) inicia el servidor como un subproceso bajo demanda y se comunica con él a través de stdin/stdout. No hay nada que "iniciar" por tu cuenta.

Claude Desktop

Abre el archivo de configuración (créalo si no existe):
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Fusiona esto en el bloque mcpServers del archivo (reemplaza los tres marcadores de posición 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"
      }
    }
  }
}
```
Obtén ABSOLUTE_PATH_TO_NODE ejecutando which node en tu terminal. No pongas simplemente "node": Claude Desktop se inicia a través de launchd con un PATH mínimo que no incluye nvm o homebrew, por lo que un "node" simple fallará silenciosamente. Lo mismo ocurre con la ruta a dist/index.js: debe ser absoluta.
Cierra completamente Claude Desktop (⌘Q en macOS; cerrar la ventana no es suficiente), luego vuelve a abrirlo.
Verifica preguntándole a Claude "list my Clicky MCP tools" (lista mis herramientas MCP de Clicky): deberías ver 11 herramientas.

Si algo sale mal, consulta Solución de problemas.

Claude Code

Un comando:

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

Esto escribe en ~/.claude.json por defecto. Añade --scope project para escribir en un .mcp.json local del proyecto en su lugar. Reinicia Claude Code (o ejecuta /mcp para actualizar) y las 11 herramientas estarán disponibles.

Inspector MCP (depuración)

Úsalo cuando quieras llamar a las herramientas directamente sin comprometer el servidor a un host; es útil para inspeccionar esquemas o solucionar problemas de respuestas:

npx @modelcontextprotocol/inspector node dist/index.js

Luego abre la URL impresa, establece CLICKY_SITE_ID y CLICKY_SITE_KEY como variables de entorno en la interfaz de usuario del Inspector (o pasa --site-id … --site-key … como argumentos de CLI después de dist/index.js), y explora.

Related MCP server: Plausible MCP Server

Parámetros de fecha

Cada herramienta que reconoce fechas acepta o bien un rango de fechas explícito o una palabra clave de fecha relativa de Clicky, pero no ambos:

Explícito: start_date + end_date, ambos en formato YYYY-MM-DD, rango ≤ 31 días.
Palabra clave: date_range, uno de today, yesterday, last-7-days, last-30-days, this-week, last-week, this-month, last-month, this-year, last-year.

Ejemplo:

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

Referencia de herramientas

Las 11 herramientas, ordenadas alfabéticamente según su caso de uso.

get_total_visitors

Recuentos totales de visitantes para un período.

start_date / end_date o date_range

get_actions

Total de visitas a páginas/acciones para un período.

start_date / end_date o date_range
limit (número, opcional, máx. 1000)

get_bounce_rate

Tasa de rebote y tiempo promedio en el sitio para un período.

start_date / end_date o date_range

get_visitors_online

Recuento de visitantes en tiempo real y segmentación. No requiere parámetros.

get_top_pages

Páginas más populares para un período.

start_date / end_date o date_range
limit (número, opcional, máx. 1000)

get_page_traffic

Datos de tráfico para una URL de página específica.

url (cadena, obligatorio)
start_date / end_date o date_range

get_traffic_sources

Desglose de fuentes de tráfico; opcionalmente filtra por URL de página.

start_date / end_date o date_range
page_url (cadena, opcional): URL completa o ruta

get_referring_domains

Dominios de referencia principales que envían tráfico.

start_date / end_date o date_range
limit (número, opcional, máx. 1000)

get_domain_visitors

Datos de visitantes filtrados por dominio de referencia, con segmentación opcional.

domain (cadena, obligatorio)
start_date / end_date o date_range
segments (matriz, opcional): ["pages", "visitors"]. Por defecto es ["visitors"].
limit (número, opcional, máx. 1000)

get_searches

Términos de búsqueda principales que trajeron visitantes.

start_date / end_date o date_range
limit (número, opcional, máx. 1000)

get_countries

Desglose de visitantes por país.

start_date / end_date o date_range
limit (número, opcional, máx. 1000)

Límites de la API

Impuestos por Clicky, no por este servidor:

Rango de fechas explícito máximo: 31 días
Resultados máximos por solicitud: 1,000 elementos
Una solicitud simultánea por IP por ID de sitio

Solución de problemas

"Claude Desktop no ve el servidor". Revisa el registro de inicio en ~/Library/Logs/Claude/mcp-server-clicky-analytics.log. La causa más común es que node no esté en el PATH de launchd de Claude Desktop; soluciónalo reemplazando "command": "node" con la ruta absoluta obtenida de which node. La segunda causa más común es olvidar cerrar completamente Claude Desktop (⌘Q, no solo cerrar la ventana).

"El rango de fechas no puede exceder los 31 días". Ese es un límite de la API de Clicky, no nuestro. Reduce el rango o usa una palabra clave de date_range como last-30-days.

Desarrollo local

Para trabajar en el servidor, no solo usarlo.

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)

Para el desarrollo local, las credenciales pueden provenir de un archivo .env en la raíz del proyecto:

CLICKY_SITE_ID=your_site_id
CLICKY_SITE_KEY=your_site_key

.env está ignorado por git. No uses .env para hosts como Claude Desktop; pasa las credenciales a través del bloque env de la configuración del host, como se muestra en Inicio rápido. El servidor solo carga .env cuando las credenciales no están ya en el entorno.

Un hook de git pre-push en .githooks/pre-push ejecuta automáticamente npm test antes de cualquier push que actualice la rama remota main, por lo que una regresión no puede pasar desapercibida. Se instala automáticamente mediante el script prepare de npm después de npm install. Los pushes a ramas de características no están restringidos. Evítalo en caso de emergencia con git push --no-verify.

Estructura del proyecto

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

Instalación de este MCP a través de un agente de IA

Si deseas que un agente de IA (por ejemplo, Claude Code en otro proyecto) instale este MCP por ti, indícale esta sección. El agente debe:

Clonar y compilar:

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

Pedir al usuario su ID de sitio y clave de sitio de Clicky (https://clicky.com/user/preferences/site).
Ejecutar which node y capturar la ruta absoluta.
Localizar la configuración de Claude Desktop del usuario (rutas en Inicio rápido › Claude Desktop) y fusionar el fragmento mcpServers de esa sección, sustituyendo la ruta absoluta de node, la ruta absoluta de dist/index.js y las credenciales del usuario.
Decirle al usuario que reinicie completamente Claude Desktop (⌘Q), luego verificar preguntando a Claude "list my Clicky MCP tools" (lista mis herramientas MCP de Clicky): deberían aparecer 11 herramientas.

Para Claude Code, el comando único claude mcp add en Inicio rápido › Claude Code es más rápido y escribe la configuración en un solo paso.

Licencia

MIT

Clicky MCP Server