Goatcounter

Interactúa con la API de análisis web de Goatcounter.

GitHub

Documentación

Servidor MCP de Goatcounter

smithery badge

Resumen

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con la API de análisis web de Goatcounter. Permite que los modelos de lenguaje u otros clientes MCP consulten fácilmente las estadísticas e información de Goatcounter mediante una interfaz de herramientas estandarizada.

El servidor está construido con Python y la librería FastMCP. Lee el código de sitio y la clave API de Goatcounter desde variables de entorno para la autenticación.

Características

  • Proporciona herramientas para la mayoría de los endpoints de la API de Goatcounter.
  • Gestiona la configuración de la clave API y el código de sitio mediante variables de entorno (GOATCOUNTER_API_KEY, GOATCOUNTER_CODE).
  • Inicialización diferida del cliente API: las herramientas pueden listarse incluso si las credenciales API aún no están configuradas.
  • Manejo de límites de velocidad: implementa reintentos automáticos con retroceso al encontrar límites de velocidad de la API (HTTP 429).
    • Prioriza el encabezado X-Rate-Limit-Reset para la espera si la API lo proporciona.
    • Recurre a un retroceso exponencial (comenzando en 1 segundo) con fluctuación aleatoria si el encabezado no está disponible o es inválido.
    • Reintenta hasta 5 veces antes de fallar.
  • Se ejecuta directamente usando la herramienta de línea de comandos fastmcp.

Instalación

Opción 1: Instalación mediante Smithery (Recomendado)

Para instalar automáticamente el servidor MCP de X (Twitter) para Claude Desktop mediante Smithery:

npx -y @smithery/cli install @rafaljanicki/goatcounter-mcp-server --client claude

Opción 2: Instalar desde PyPI

La forma más sencilla de instalar goatcounter-mcp-server es mediante PyPI:

pip install goatcounter-mcp-server

O instalar directamente desde el repositorio:

pip install git+https://github.com/rafaljanicki/goatcounter-mcp-server.git

Opción 3: Instalar desde el código fuente

Si prefieres instalar desde el repositorio fuente:

  1. Clonar el repositorio:

    git clone https://github.com/rafaljanicki/goatcounter-mcp-server
cd goatcounter-mcp-server

  2. Crear un entorno virtual:

    python3.13 -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

  3. Instalar dependencias: Instala FastMCP y otros paquetes requeridos:

    pip install -r requirements.txt

  4. Configurar variables de entorno: Copia el archivo de ejemplo .env.example a .env:

    cp .env.example .env

    Edita el archivo .env y añade los detalles de tu Goatcounter (consulta la sección de Variables de Entorno a continuación).

Variables de Entorno

El servidor requiere que se establezcan las siguientes variables de entorno:

  • GOATCOUNTER_CODE: El código de sitio de tu Goatcounter (la parte del subdominio, por ejemplo, 'mycoolsite').
  • GOATCOUNTER_API_KEY: Tu token API de Goatcounter. Puedes generar uno en tu sitio de Goatcounter en Configuración -> Tokens API. Asegúrate de que tenga los permisos necesarios para las acciones de API que pretendes usar.

Puedes establecer estas variables directamente en tu entorno o colocarlas en un archivo .env en la raíz del proyecto.

Ejecutar el Servidor

Opción 1: Usar el script CLI

El proyecto define un script CLI goatcounter-mcp-server.

Si se instala desde PyPI:

goatcounter-mcp-server

Si se instala desde el código fuente con uv:

uv run goatcounter-mcp-server

Opción 2: Usar FastMCP directamente (solo desde el código fuente)

Si instalaste desde el código fuente y prefieres ejecutar el servidor usando el modo de desarrollo de FastMCP:

fastmcp dev src/goatcounter_mcp_server/server.py

Uso con Claude Desktop

Para usar este servidor MCP con Claude Desktop, necesitas configurar Claude para conectarse al servidor. Sigue estos pasos:

Paso 1: Instalar Node.js

Claude Desktop usa Node.js para ejecutar servidores MCP. Si no tienes Node.js instalado:

  • Descarga e instala Node.js desde nodejs.org.
  • Verifica la instalación: 
    node --version

Paso 2: Localizar la configuración de Claude Desktop

Claude Desktop usa un archivo claude_desktop_config.json para configurar los servidores MCP.

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

Si el archivo no existe, créalo.

Paso 3: Configurar el servidor MCP

Edita claude_desktop_config.json para incluir el servidor goatcounter-mcp-server. Reemplaza /path/to/goatcounter-mcp-server con la ruta real a tu directorio del proyecto (si se instaló desde el código fuente) o la ruta a tu ejecutable de Python (si se instaló desde PyPI).

Si se instala desde PyPI:

{
  "mcpServers": {
    "goatcounter-mcp-server": {
      "command": "goatcounter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "GOATCOUNTER_CODE": "goatcounter_code",
        "GOATCOUNTER_API_KEY": "goatcounter_api_key"
      }
    }
  }
}

Si se instala desde el código fuente con uv:

{
  "mcpServers": {
    "goatcounter-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/goatcounter-mcp-server",
        "run",
        "goatcounter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "GOATCOUNTER_CODE": "goatcounter_code",
        "GOATCOUNTER_API_KEY": "goatcounter_api_key"
      }
    }
  }
}
  • "command": "goatcounter-mcp-server": Usa el script CLI directamente si se instaló desde PyPI.
  • "env": Si se instaló desde PyPI, es posible que necesites proporcionar variables de entorno directamente en la configuración (ya que no hay un archivo .env). Si se instaló desde el código fuente, se usará el archivo .env.
  • "env": {"PYTHONUNBUFFERED": "1"}: Asegura que la salida no esté almacenada en búfer para un mejor registro en Claude.

Paso 4: Reiniciar Claude Desktop

  • Cierra Claude Desktop por completo.
  • Vuelve a abrir Claude Desktop para cargar la nueva configuración.

Paso 5: Verificar la conexión

  • Abre Claude Desktop.
  • Busca un icono de martillo o conector en el área de entrada (esquina inferior derecha). Esto indica que las herramientas MCP están disponibles.
  • Haz clic en el icono para ver las herramientas disponibles de goatcounter-mcp-server

Documentación de la API: Herramientas Disponibles

Las siguientes herramientas MCP están disponibles:

Herramienta: Goatcounter_get_me

Obtén información sobre el usuario actual de Goatcounter y la clave API asociada con el GOATCOUNTER_API_KEY configurado.

  • Parámetros: Ninguno
  • Devuelve: object - Información sobre el usuario y el token.

Herramienta: Goatcounter_list_sites

Lista todos los sitios de Goatcounter accesibles con la clave API actual.

  • Parámetros: Ninguno
  • Devuelve: object - Una lista de sitios accesibles.

Herramienta: Goatcounter_list_paths

Obtén una descripción general de las rutas rastreadas en este sitio (sin estadísticas).

  • Parámetros:
    • limit (entero, opcional): Limita el número de resultados devueltos (1-200, predeterminado 20).
    • after (entero, opcional): Solo selecciona rutas después de este ID de ruta, para paginación.
  • Devuelve: object - Una lista de rutas e información de paginación.

Herramienta: Goatcounter_get_stats_total

Obtén el número total de visitas a páginas y visitantes únicos para el sitio dentro de un período especificado.

  • Parámetros:
    • start (cadena, opcional): Fecha de inicio (AAAA-MM-DD o relativa, por ejemplo, 'hace 7 días').
    • end (cadena, opcional): Fecha de fin (AAAA-MM-DD o relativa, por ejemplo, 'ayer').
    • filter (cadena, opcional): Filtrar rutas (por ejemplo, '/blog*').
    • daily (booleano, opcional): Mostrar estadísticas diarias en lugar de totales (predeterminado: falso).
  • Devuelve: object - Estadísticas totales o estadísticas diarias si daily es verdadero.

Herramienta: Goatcounter_get_stats_hits

Lista estadísticas de páginas (visitas a páginas y visitantes por ruta).

  • Parámetros:
    • start (cadena, opcional): Fecha de inicio (AAAA-MM-DD o relativa, por ejemplo, 'hace 7 días').
    • end (cadena, opcional): Fecha de fin (AAAA-MM-DD o relativa, por ejemplo, 'ayer').
    • filter (cadena, opcional): Filtrar rutas (por ejemplo, '/blog*').
    • daily (booleano, opcional): Mostrar estadísticas diarias en lugar de totales (predeterminado: falso).
    • limit (entero, opcional): Limita el número de resultados devueltos (1-200, predeterminado 20).
    • after (entero, opcional): Cursor de paginación.
  • Devuelve: object - Una lista de estadísticas de rutas e información de paginación.

Herramienta: Goatcounter_get_stats_refs

Lista estadísticas de referentes.

  • Parámetros:
    • start (cadena, opcional): Fecha de inicio (AAAA-MM-DD o relativa, por ejemplo, 'hace 7 días').
    • end (cadena, opcional): Fecha de fin (AAAA-MM-DD o relativa, por ejemplo, 'ayer').
    • filter (cadena, opcional): Filtrar rutas (por ejemplo, '/blog*').
    • daily (booleano, opcional): Mostrar estadísticas diarias en lugar de totales (predeterminado: falso).
    • limit (entero, opcional): Limita el número de resultados devueltos (1-200, predeterminado 20).
    • after (entero, opcional): Cursor de paginación.
  • Devuelve: object - Una lista de estadísticas de referentes e información de paginación.

Herramienta: Goatcounter_get_stats_browsers

Lista estadísticas de navegadores.

  • Parámetros:
    • start (cadena, opcional): Fecha de inicio (AAAA-MM-DD o relativa, por ejemplo, 'hace 7 días').
    • end (cadena, opcional): Fecha de fin (AAAA-MM-DD o relativa, por ejemplo, 'ayer').
    • filter (cadena, opcional): Filtrar rutas (por ejemplo, '/blog*').
    • daily (booleano, opcional): Mostrar estadísticas diarias en lugar de totales (predeterminado: falso).
    • limit (entero, opcional): Limita el número de resultados devueltos (1-200, predeterminado 20).
    • after (entero, opcional): Cursor de paginación.
  • Devuelve: object - Una lista de estadísticas de navegadores e información de paginación.

Herramienta: Goatcounter_get_stats_systems

Lista estadísticas de sistemas operativos.

  • Parámetros:
    • start (cadena, opcional): Fecha de inicio (AAAA-MM-DD o relativa, por ejemplo, 'hace 7 días').
    • end (cadena, opcional): Fecha de fin (AAAA-MM-DD o relativa, por ejemplo, 'ayer').
    • filter (cadena, opcional): Filtrar rutas (por ejemplo, '/blog*').
    • daily (booleano, opcional): Mostrar estadísticas diarias en lugar de totales (predeterminado: falso).
    • limit (entero, opcional): Limita el número de resultados devueltos (1-200, predeterminado 20).
    • after (entero, opcional): Cursor de paginación.
  • Devuelve: object - Una lista de estadísticas de sistemas operativos e información de paginación.

Herramienta: Goatcounter_get_stats_sizes

Lista estadísticas de tamaños de pantalla.

  • Parámetros:
    • start (cadena, opcional): Fecha de inicio (AAAA-MM-DD o relativa, por ejemplo, 'hace 7 días').
    • end (cadena, opcional): Fecha de fin (AAAA-MM-DD o relativa, por ejemplo, 'ayer').
    • filter (cadena, opcional): Filtrar rutas (por ejemplo, '/blog*').
    • daily (booleano, opcional): Mostrar estadísticas diarias en lugar de totales (predeterminado: falso).
    • limit (entero, opcional): Limita el número de resultados devueltos (1-200, predeterminado 20).
    • after (entero, opcional): Cursor de paginación.
  • Devuelve: object - Una lista de estadísticas de tamaños de pantalla e información de paginación.

Herramienta: Goatcounter_get_stats_locations

Lista estadísticas de ubicaciones.

  • Parámetros:
    • start (cadena, opcional): Fecha de inicio (AAAA-MM-DD o relativa, por ejemplo, 'hace 7 días').
    • end (cadena, opcional): Fecha de fin (AAAA-MM-DD o relativa, por ejemplo, 'ayer').
    • filter (cadena, opcional): Filtrar rutas (por ejemplo, '/blog*').
    • daily (booleano, opcional): Mostrar estadísticas diarias en lugar de totales (predeterminado: falso).
    • limit (entero, opcional): Limita el número de resultados devueltos (1-200, predeterminado 20).
    • after (entero, opcional): Cursor de paginación.
  • Devuelve: object - Una lista de estadísticas de ubicaciones e información de paginación.

Uso

  1. Establecer variables de entorno: Crea un archivo .env en la raíz de tu proyecto o establece las variables de entorno directamente:

    GOATCOUNTER_CODE=your_site_code
GOATCOUNTER_API_KEY=your_goatcounter_api_key

    Puedes generar una clave API en la configuración de tu cuenta de Goatcounter.

  2. Ejecutar con FastMCP: Integra este servidor con tu configuración de FastMCP. Consulta la documentación de FastMCP para obtener detalles sobre cómo conectar servidores MCP.

    El servidor registra herramientas con el prefijo Goatcounter (por ejemplo, Goatcounter.list_sites).

Desarrollo

  • Instala las dependencias de desarrollo: pip install -e ".[dev]" (si las dependencias de desarrollo están especificadas en pyproject.toml)
  • Este proyecto usa hatch para la compilación.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un problema o envía una solicitud de extracción.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.