ActivityWatch MCP Server

Un servidor MCP para ActivityWatch que permite la interacción con tus datos personales de seguimiento de tiempo.

GitHub
73
Prueba este MCPPatrocinado

Documentación

Servidor MCP de ActivityWatch

Un servidor del Protocolo de Contexto de Modelos (MCP) que se conecta a ActivityWatch, permitiendo que LLMs como Claude interactúen con tus datos de seguimiento de tiempo.

ActivityWatch Server MCP server

Características

  • Listar Buckets: Ver todos los buckets disponibles de ActivityWatch
  • Ejecutar Consultas: Ejecutar potentes consultas AQL (Lenguaje de Consulta de ActivityWatch)
  • Obtener Eventos Crudos: Recuperar eventos directamente de cualquier bucket
  • Obtener Configuración: Acceder a los ajustes de configuración de ActivityWatch

Instalación

Puedes instalar el servidor MCP de ActivityWatch desde npm o compilándolo tú mismo.

Instalación desde npm (próximamente)

# Global installation
npm install -g activitywatch-mcp-server

# Or install locally
npm install activitywatch-mcp-server

Compilación desde el Código Fuente

  1. Clona este repositorio:

    git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git
cd activitywatch-mcp-server

  2. Instala las dependencias:

    npm install

  3. Compila el proyecto:

    npm run build

Requisitos Previos

  • ActivityWatch instalado y en ejecución
  • Node.js (v14 o superior)
  • Claude para Desktop (o cualquier otro cliente MCP)

Uso

Uso con Claude para Desktop

  1. Abre tu archivo de configuración de Claude para Desktop:

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

  2. Añade la configuración del servidor MCP:

    {
"mcpServers": {
    "activitywatch": {
    "command": "activitywatch-mcp-server",
    "args": []
    }
}
}

    Si compilaste desde el código fuente, usa:

    {
"mcpServers": {
    "activitywatch": {
    "command": "node",
    "args": ["/path/to/activitywatch-mcp-server/dist/index.js"]
    }
}
}

  3. Reinicia Claude para Desktop

  4. Busca el icono de MCP en la interfaz de Claude para confirmar que funciona

Uso de un contenedor podman sin root en Linux con Gemini CLI

Asegúrate de compilar la imagen primero con:

version=$(npm pkg get version | tr -d '"')
podman build . -t activitywatch-mcp-server:${version}

Este ejemplo usa la anulación para que Activity Watch no esté disponible en 127.0.0.1 (ver la siguiente sección). Si no es necesario, puedes omitir la variable de entorno AW_API_BASE.

{
  "mcpServers": {
    "activitywatch-mcp-server": {
      "command": "/usr/bin/podman",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--userns=keep-id",
        "-e",
        "AW_API_BASE",
        "localhost/activitywatch-mcp-server:1.2.1"
      ],
      "env": {
        "AW_API_BASE": "http://mydesktop.local:5600/api/0"
      }
    }
  }
}

Anular el host/puerto del servidor de ActivityWatch

Si quieres ejecutar este servidor MCP desde dentro del Subsistema de Windows para Linux, por ejemplo dentro de un contenedor, el servidor AW que se ejecuta en Windows no estará disponible en 127.0.0.1. Para anular la conexión estándar de localhost, usa la variable de entorno AW_API_BASE o la bandera --aw-api-base, como se muestra a continuación:

# Using environment variable
export AW_API_BASE=http://mydesktop.local:5600/api/0
node dist/index.js

# Or using command-line flag
node dist/index.js --aw-api-base=http://mydesktop.local:5600/api/0

NOTA: El servidor AW puede ser exigente con el nombre usado para conectarse a él, pero aceptará un nombre que coincida con el nombre del equipo donde se ejecuta con un sufijo .local.

Ejemplos de Consultas

Aquí hay algunos ejemplos de consultas que puedes probar en Claude:

  • Listar todos tus buckets: "¿Qué buckets de ActivityWatch tengo?"
  • Obtener resumen de uso de aplicaciones: "¿Puedes mostrarme qué aplicaciones he usado más hoy?"
  • Ver historial de navegación: "¿En qué sitios web he pasado más tiempo hoy?"
  • Comprobar productividad: "¿Cuánto tiempo he pasado en aplicaciones de productividad hoy?"
  • Ver configuración: "¿Cuáles son mis ajustes de ActivityWatch?" o "¿Puedes comprobar un ajuste específico en ActivityWatch?"

Herramientas Disponibles

list-buckets

Lista todos los buckets disponibles de ActivityWatch con filtrado opcional por tipo.

Parámetros:

  • type (opcional): Filtrar buckets por tipo (por ejemplo, "window", "web", "afk")
  • includeData (opcional): Incluir datos del bucket en la respuesta

run-query

Ejecuta una consulta en el lenguaje de consulta de ActivityWatch (AQL).

Parámetros:

  • timeperiods: Período(s) de tiempo a consultar formateados como un array de cadenas. Para rangos de fechas, usa el formato: ["2024-10-28/2024-10-29"]
  • query: Array de declaraciones de consulta en el Lenguaje de Consulta de ActivityWatch, donde cada elemento es una consulta completa con declaraciones separadas por punto y coma
  • name (opcional): Nombre para la consulta (usado para caché)

IMPORTANTE: Cada cadena de consulta debe contener una consulta completa con múltiples declaraciones separadas por punto y coma.

Ejemplo de formato de solicitud:

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}

Ten en cuenta que:

  • timeperiods debe tener rangos de fechas preformateados con barras
  • Cada elemento en el array query es una consulta completa con todas las declaraciones

get-events

Obtiene eventos crudos de un bucket de ActivityWatch.

Parámetros:

  • bucketId: ID del bucket del que obtener eventos
  • start (opcional): Fecha/hora de inicio en formato ISO
  • end (opcional): Fecha/hora de fin en formato ISO
  • limit (opcional): Número máximo de eventos a devolver

get-settings

Obtiene los ajustes de ActivityWatch del servidor.

Parámetros:

  • key (opcional): Obtener una clave de ajuste específica en lugar de todos los ajustes

Ejemplos de Lenguaje de Consulta

ActivityWatch usa un lenguaje de consulta simple. Aquí hay algunos patrones comunes:

// Get window events
window_events = query_bucket(find_bucket("aw-watcher-window_"));
RETURN = window_events;

// Get only when not AFK
afk_events = query_bucket(find_bucket("aw-watcher-afk_"));
not_afk = filter_keyvals(afk_events, "status", ["not-afk"]);
window_events = filter_period_intersect(window_events, not_afk);
RETURN = window_events;

// Group by app
window_events = query_bucket(find_bucket("aw-watcher-window_"));
events_by_app = merge_events_by_keys(window_events, ["app"]);
RETURN = sort_by_duration(events_by_app);

// Filter by app name
window_events = query_bucket(find_bucket("aw-watcher-window_"));
code_events = filter_keyvals(window_events, "app", ["Code"]);
RETURN = code_events;

Configuración

El servidor se conecta a la API de ActivityWatch en http://localhost:5600 por defecto. Si tu instancia de ActivityWatch se ejecuta en un host o puerto diferente, puedes anularlo como se describe en la sección Anular el host/puerto del servidor de ActivityWatch anterior.

Solución de Problemas

ActivityWatch No Está en Ejecución

Si ActivityWatch no está en ejecución, el servidor mostrará errores de conexión. Asegúrate de que ActivityWatch esté en ejecución y sea accesible en la dirección host/puerto especificada (http://localhost:5600 a menos que la hayas anulado).

Errores de Consulta

Si encuentras errores de consulta:

  1. Comprueba la sintaxis de tu consulta
  2. Asegúrate de que los IDs de bucket sean correctos
  3. Verifica que los períodos de tiempo contengan datos
  4. Revisa los registros de ActivityWatch para más detalles

Problemas de Formato de Consulta en Claude/MCP

Si Claude reporta errores al ejecutar consultas a través de este servidor MCP, es probable que se deba a problemas de formato. Asegúrate de que tu consulta siga este formato exacto en tus indicaciones:

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}

Problemas comunes:

  • Períodos de tiempo no formateados correctamente (deben ser "inicio/fin" en una sola cadena dentro de un array)
  • Declaraciones de consulta divididas en elementos de array separados en lugar de combinadas en una sola cadena

El Problema de Formato Más Común

El error más frecuente es cuando Claude divide cada declaración de consulta en su propio elemento de array de esta manera:

{
  "query": [
    "browser_events = query_bucket('aw-watcher-web');",
    "afk_events = query_bucket('aw-watcher-afk');",
    "RETURN = events;"
  ],
  "timeperiods": ["2024-10-28/2024-10-29"]
}

Esto es INCORRECTO. En su lugar, todas las declaraciones deben estar en una sola cadena dentro del array:

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["browser_events = query_bucket('aw-watcher-web'); afk_events = query_bucket('aw-watcher-afk'); RETURN = events;"]
}

Al Indicar a Claude

Al indicar a Claude, sé muy explícito sobre el formato y usa ejemplos. Por ejemplo, di:

"Ejecuta una consulta con períodos de tiempo como ["2024-10-28/2024-10-29"] y consulta como ["statement1; statement2; RETURN = result;"]. Importante: Asegúrate de que TODAS las declaraciones de consulta estén en una sola cadena dentro del array, no divididas en elementos de array separados."

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción.

Licencia

MIT