hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Servidor MCP de ActivityWatch

Un servidor de Protocolo de contexto de modelo (MCP) que se conecta a ActivityWatch , lo que permite que los LLM como Claude interactúen con sus datos de seguimiento de tiempo.

Características

Lista de depósitos : ver todos los depósitos de ActivityWatch disponibles
Ejecutar consultas : ejecute potentes consultas AQL (lenguaje de consulta de ActivityWatch)
Obtener eventos sin procesar : recupera eventos directamente desde cualquier bucket
Obtener configuración : acceder a la configuración de ActivityWatch

Instalación

Puede instalar el servidor MCP de ActivityWatch desde npm o compilándolo usted mismo.

Instalación desde npm (próximamente)

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

# Or install locally
npm install activitywatch-mcp-server

Construyendo desde la fuente

Clonar este repositorio:
git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git cd activitywatch-mcp-server
Instalar dependencias:
npm install
Construir el proyecto:
npm run build

Prerrequisitos

ActivityWatch instalado y funcionando
Node.js (v14 o superior)
Claude para escritorio (o cualquier otro cliente MCP)

Uso

Uso con Claude para escritorio

Abra el archivo de configuración de Claude for Desktop:
- Ventanas: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Agregue la configuración del servidor MCP:

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

Si lo construiste desde la fuente, usa:

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

Reiniciar Claude para escritorio
Busque el ícono MCP en la interfaz de Claude para confirmar que funciona

Consultas de ejemplo

A continuación se muestran algunos ejemplos de consultas que puedes probar en Claude:

Enumere todos sus depósitos : "¿Qué depósitos de ActivityWatch tengo?"
Obtener un resumen de uso de la aplicación : "¿Puede mostrarme qué aplicaciones he usado más hoy?"
Ver el historial de navegación : "¿En qué sitios web he pasado más tiempo hoy?"
Comprobar la productividad : "¿Cuánto tiempo he pasado en aplicaciones de productividad hoy?"
Ver configuración : "¿Cuáles son mis configuraciones de ActivityWatch?" o "¿Puedes consultar una configuración específica en ActivityWatch?"

Herramientas disponibles

lista de cubos

Enumera todos los depósitos de ActivityWatch disponibles con filtrado de tipo opcional.

Parámetros:

type (opcional): Filtra los grupos por tipo (por ejemplo, "ventana", "web", "afk")
includeData (opcional): incluye datos del depósito en la respuesta

ejecutar consulta

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

Parámetros:

timeperiods : Periodo(s) de consulta, formateados como una matriz de cadenas. Para rangos de fechas, utilice el formato: ["2024-10-28/2024-10-29"]
query : Matriz 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 almacenamiento en 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;"]
}

Tenga en cuenta que:

timeperiods deben tener rangos de fechas preformateados con barras
Cada elemento de la matriz query es una consulta completa con todas las declaraciones

obtener eventos

Obtenga eventos sin procesar de un depósito ActivityWatch.

Parámetros:

bucketId : ID del depósito del que se obtendrán los eventos
start (opcional): Fecha/hora de inicio en formato ISO
end (opcional): Fecha/hora de finalización en formato ISO
limit (opcional): Número máximo de eventos a devolver

obtener configuraciones

Obtenga la configuración de ActivityWatch del servidor.

Parámetros:

key (opcional): obtener una clave de configuración específica en lugar de todas las configuraciones

Ejemplos de lenguaje de consulta

ActivityWatch utiliza un lenguaje de consulta sencillo. A continuación, se muestran 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 de forma predeterminada. Si su instancia de ActivityWatch se ejecuta en un host o puerto diferente, puede modificarlo en el código fuente.

Solución de problemas

ActivityWatch no funciona

Si ActivityWatch no se está ejecutando, el servidor mostrará errores de conexión. Asegúrese de que ActivityWatch se esté ejecutando y sea accesible en http://localhost:5600 .

Errores de consulta

Si encuentra errores de consulta:

Comprueba la sintaxis de tu consulta
Asegúrese de que los identificadores de los depósitos sean correctos
Verificar que los periodos de tiempo contengan datos
Consulte los registros de ActivityWatch para obtener más detalles

Problemas de formato de consultas de Claude/MCP

Si Claude informa errores al ejecutar consultas a través de este servidor MCP, probablemente se deba a problemas de formato. Asegúrese de que su consulta siga exactamente este formato en sus indicaciones:

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

Problemas comunes:

Los períodos de tiempo no están formateados correctamente (deberían ser "inicio/fin" en una sola cadena dentro de una matriz)
Las declaraciones de consulta se dividen en elementos de matriz separados en lugar de combinarse en una 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 matriz 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 deberían 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 incitar a Claude

Al darle indicaciones a Claude, sea muy explícito sobre el formato y use ejemplos. Por ejemplo, diga:

Ejecute una consulta con los períodos ["2024-10-28/2024-10-29"] y la consulta ["statement1; statement2; RETURN = result;"] . Importante: Asegúrese de que TODAS las sentencias de consulta estén en una sola cadena dentro de la matriz, no divididas en elementos separados.

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Licencia

Instituto Tecnológico de Massachusetts (MIT)

You must be authenticated.

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

Tools

Una interfaz que permite que modelos de lenguaje grandes como Claude interactúen con los datos de seguimiento de tiempo de ActivityWatch a través del Protocolo de contexto de modelo, lo que permite realizar consultas sobre el uso de la aplicación, el historial de navegación y los patrones de productividad.

Related Resources

Reddit Discussion about this server

Appeared in Searches

A server for searching and accessing emails