ActivityWatch MCP Server

Um servidor MCP para o ActivityWatch, permitindo interação com seus dados pessoais de rastreamento de tempo.

GitHub
72

Documentação

ActivityWatch MCP Server

Um servidor Model Context Protocol (MCP) que se conecta ao ActivityWatch, permitindo que LLMs como o Claude interajam com seus dados de monitoramento de tempo.

ActivityWatch Server MCP server

Recursos

  • Listar Buckets: Visualize todos os buckets disponíveis do ActivityWatch
  • Executar Consultas: Execute consultas poderosas em AQL (ActivityWatch Query Language)
  • Obter Eventos Brutos: Recupere eventos diretamente de qualquer bucket
  • Obter Configurações: Acesse as configurações do servidor ActivityWatch

Instalação

Você pode instalar o servidor ActivityWatch MCP pelo npm ou compilando-o você mesmo.

Instalando pelo npm (em breve)

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

# Or install locally
npm install activitywatch-mcp-server

Compilando a partir do código-fonte

  1. Clone este repositório:

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

  2. Instale as dependências:

    npm install

  3. Compile o projeto:

    npm run build

Pré-requisitos

  • ActivityWatch instalado e em execução
  • Node.js (v14 ou superior)
  • Claude for Desktop (ou qualquer outro cliente MCP)

Uso

Usando com o Claude for Desktop

  1. Abra o arquivo de configuração do Claude for Desktop:

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

  2. Adicione a configuração do servidor MCP:

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

    Se você compilou a partir do código-fonte, use:

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

  3. Reinicie o Claude for Desktop

  4. Procure pelo ícone do MCP na interface do Claude para confirmar que está funcionando

Usando um contêiner podman sem root no Linux com o Gemini CLI

Certifique-se de compilar a imagem primeiro com:

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

Este exemplo usa a substituição para o Activity Watch não estar disponível no 127.0.0.1 (veja a próxima seção). Se não for necessário, você pode omitir a variável de ambiente 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"
      }
    }
  }
}

Substituir host/porta do servidor ActivityWatch

Se você quiser executar este servidor MCP de dentro do Windows Subsystem for Linux, por exemplo, dentro de um contêiner, o servidor AW em execução no Windows não estará disponível em 127.0.0.1. Para substituir a conexão localhost padrão, use a variável de ambiente AW_API_BASE ou o sinalizador --aw-api-base, conforme abaixo:

# 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: O servidor AW pode ser exigente quanto ao nome usado para se conectar a ele, mas aceitará um nome que corresponda ao nome do computador onde está em execução com o sufixo .local.

Exemplos de consultas

Aqui estão alguns exemplos de consultas que você pode testar no Claude:

  • Listar todos os seus buckets: "Quais buckets do ActivityWatch eu tenho?"
  • Obter resumo de uso de aplicativos: "Você pode me mostrar quais aplicativos eu mais usei hoje?"
  • Visualizar histórico de navegação: "Em quais sites passei mais tempo hoje?"
  • Verificar produtividade: "Quanto tempo passei em aplicativos de produtividade hoje?"
  • Visualizar configurações: "Quais são minhas configurações do ActivityWatch?" ou "Você pode verificar uma configuração específica no ActivityWatch?"

Ferramentas disponíveis

list-buckets

Lista todos os buckets disponíveis do ActivityWatch com filtro opcional por tipo.

Parâmetros:

  • type (opcional): Filtra buckets por tipo (ex.: "window", "web", "afk")
  • includeData (opcional): Inclui dados dos buckets na resposta

run-query

Executa uma consulta na linguagem de consulta do ActivityWatch (AQL).

Parâmetros:

  • timeperiods: Período(s) de tempo a consultar, formatado como array de strings. Para intervalos de datas, use o formato: ["2024-10-28/2024-10-29"]
  • query: Array de declarações de consulta em ActivityWatch Query Language, onde cada item é uma consulta completa com declarações separadas por ponto e vírgula
  • name (opcional): Nome para a consulta (usado para cache)

IMPORTANTE: Cada string de consulta deve conter uma consulta completa com múltiplas declarações separadas por ponto e vírgula.

Exemplo de formato de solicitação:

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

Observe que:

  • timeperiods deve ter intervalos de datas pré-formatados com barras
  • Cada item no array query é uma consulta completa com todas as declarações

get-events

Obtém eventos brutos de um bucket do ActivityWatch.

Parâmetros:

  • bucketId: ID do bucket do qual buscar eventos
  • start (opcional): Data/hora inicial no formato ISO
  • end (opcional): Data/hora final no formato ISO
  • limit (opcional): Número máximo de eventos a retornar

get-settings

Obtém as configurações do ActivityWatch do servidor.

Parâmetros:

  • key (opcional): Obtém uma chave de configuração específica em vez de todas as configurações

Exemplos de linguagem de consulta

O ActivityWatch usa uma linguagem de consulta simples. Aqui estão alguns padrões comuns:

// 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;

Configuração

O servidor se conecta à API do ActivityWatch em http://localhost:5600 por padrão. Se a sua instância do ActivityWatch estiver em execução em um host ou porta diferente, você pode substituí-lo conforme descrito na seção Substituir host/porta do servidor ActivityWatch acima.

Solução de problemas

ActivityWatch não está em execução

Se o ActivityWatch não estiver em execução, o servidor mostrará erros de conexão. Certifique-se de que o ActivityWatch esteja em execução e acessível no endereço host/porta especificado (http://localhost:5600 a menos que você o tenha substituído).

Erros de consulta

Se você estiver encontrando erros de consulta:

  1. Verifique a sintaxe da sua consulta
  2. Certifique-se de que os IDs dos buckets estejam corretos
  3. Verifique se os períodos de tempo contêm dados
  4. Verifique os logs do ActivityWatch para mais detalhes

Problemas de formatação de consulta do Claude/MCP

Se o Claude relatar erros ao executar consultas por meio deste servidor MCP, provavelmente é devido a problemas de formatação. Certifique-se de que sua consulta siga exatamente este formato em seus prompts:

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

Problemas comuns:

  • Períodos de tempo não formatados corretamente (devem ser "início/fim" em uma única string dentro de um array)
  • Declarações de consulta divididas em elementos separados do array em vez de combinadas em uma única string

O Problema de Formatação Mais Comum

O erro mais frequente é quando o Claude divide cada declaração de consulta em seu próprio elemento do array, assim:

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

Isso está INCORRETO. Em vez disso, todas as declarações devem estar em uma única string dentro do 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;"]
}

Ao Solicitar ao Claude

Ao solicitar ao Claude, seja bem explícito sobre o formato e use exemplos. Por exemplo, diga:

"Execute uma consulta com períodos de tempo como ["2024-10-28/2024-10-29"] e consulta como ["statement1; statement2; RETURN = result;"]. Importante: certifique-se de que TODAS as declarações da consulta estejam em uma única string dentro do array, não divididas em elementos separados do array."

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

MIT