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.

Características

• Listar buckets: Ver todos los buckets de ActivityWatch disponibles

• Ejecutar consultas: Ejecutar potentes consultas AQL (ActivityWatch Query Language)

• Obtener eventos sin procesar: Recuperar eventos directamente de cualquier bucket

• Obtener ajustes: Acceder a los ajustes de configuración de ActivityWatch

Related MCP server: Paprika SQL MCP Server

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 for Desktop (o cualquier otro cliente MCP)

Uso

Uso con Claude for Desktop

1. Abre tu archivo de configuración de Claude for 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 lo compilaste desde el código fuente, usa:

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

3. Reinicia Claude for 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 utiliza la anulación para cuando 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 deseas 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 local estándar, utiliza la variable de entorno AW_API_BASE o el flag --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 utilizado para conectarse a él, pero aceptará un nombre que coincida con el nombre del equipo donde se está ejecutando con un sufijo .local.

Ejemplos de consultas

Aquí tienes algunas consultas de ejemplo 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: "¿Qué sitios web he visitado más hoy?"

• Comprobar productividad: "¿Cuánto tiempo he pasado en aplicaciones de productividad hoy?"

• Ver ajustes: "¿Cuáles son mis ajustes de ActivityWatch?" o "¿Puedes comprobar un ajuste específico en ActivityWatch?"

Herramientas disponibles

list-buckets

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

Parámetros:

• type (opcional): Filtrar buckets por tipo (ej. "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: Periodo(s) de tiempo a consultar formateado como una matriz de cadenas. Para rangos de fechas, usa el formato: ["2024-10-28/2024-10-29"]

• query: Matriz de sentencias de consulta en el lenguaje de consulta de ActivityWatch, donde cada elemento es una consulta completa con sentencias separadas por puntos y coma

• name (opcional): Nombre para la consulta (usado para caché)

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

Formato de solicitud de ejemplo:

{
  "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 diagonales

• Cada elemento en la matriz query es una consulta completa con todas las sentencias

get-events

Obtener eventos sin procesar de un bucket de ActivityWatch.

Parámetros:

• bucketId: ID del bucket del cual 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

Obtener ajustes de ActivityWatch desde el servidor.

Parámetros:

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

Ejemplos de lenguaje de consulta

ActivityWatch utiliza un lenguaje de consulta sencillo. 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 accesible en la dirección de host/puerto especificada (http://localhost:5600 a menos que lo 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 los buckets sean correctos

3. Verifica que los periodos de tiempo contengan datos

4. Comprueba los registros de ActivityWatch para más detalles

Problemas de formato de consulta en Claude/MCP

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

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

Problemas comunes:

• Periodos de tiempo no formateados correctamente (debería ser "inicio/fin" en una sola cadena dentro de una matriz)

• Sentencias de consulta divididas en elementos de matriz separados en lugar de combinarse en una sola cadena

El problema de formato más común

El error más frecuente es cuando Claude divide cada sentencia de consulta en su propio elemento de matriz como este:

{
  "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 sentencias deben estar en una sola cadena dentro de la matriz:

{
  "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 pedirle cosas a Claude

Cuando le pidas cosas a Claude, sé muy explícito sobre el formato y usa ejemplos. Por ejemplo, di:

"Ejecuta una consulta con timeperiods como ["2024-10-28/2024-10-29"] y query como ["sentencia1; sentencia2; RETURN = resultado;"]. Importante: Asegúrate de que TODAS las sentencias de consulta estén en una sola cadena dentro de la matriz, no divididas en elementos de matriz separados."

Contribución

¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar un Pull Request.

Licencia

MIT