hybrid server

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

ActivityWatch MCP 서버

Claude와 같은 LLM이 시간 추적 데이터와 상호 작용할 수 있도록 ActivityWatch 에 연결되는 MCP(Model Context Protocol) 서버입니다.

특징

버킷 목록 : 사용 가능한 모든 ActivityWatch 버킷 보기
쿼리 실행 : 강력한 AQL(ActivityWatch 쿼리 언어) 쿼리를 실행합니다.
원시 이벤트 가져오기 : 모든 버킷에서 직접 이벤트를 검색합니다.
설정 가져오기 : ActivityWatch 구성 설정에 액세스

설치

npm에서 ActivityWatch MCP 서버를 설치하거나 직접 빌드하여 설치할 수 있습니다.

npm에서 설치(곧 제공)

지엑스피1

소스에서 빌드

이 저장소를 복제하세요:
git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git cd activitywatch-mcp-server
종속성 설치:
npm install
프로젝트를 빌드하세요:
npm run build

필수 조건

ActivityWatch가 설치되고 실행 중입니다.
Node.js(v14 이상)
데스크톱용 Claude(또는 다른 MCP 클라이언트)

용법

Claude와 함께 데스크톱 사용

Claude for Desktop 구성 파일을 엽니다.
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
MCP 서버 구성을 추가합니다.

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

소스에서 빌드한 경우 다음을 사용하세요.

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

데스크톱용 Claude를 다시 시작하세요
Claude 인터페이스에서 MCP 아이콘을 찾아 작동하는지 확인하세요.

예제 쿼리

다음은 Claude에서 시도해 볼 수 있는 몇 가지 쿼리 예시입니다.

모든 버킷을 나열하세요 : "내가 가지고 있는 ActivityWatch 버킷은 무엇인가요?"
애플리케이션 사용 요약 받기 : "오늘 제가 가장 많이 사용한 애플리케이션이 무엇인지 보여 주시겠습니까?"
검색 기록 보기 : "오늘 가장 많은 시간을 보낸 웹사이트는 어디인가요?"
생산성 확인하기 : "오늘 생산성 앱에서 얼마나 많은 시간을 보냈나요?"
설정 보기 : "ActivityWatch 설정은 어떻게 되나요?" 또는 "ActivityWatch에서 특정 설정을 확인할 수 있나요?"

사용 가능한 도구

리스트 버킷

선택적인 유형 필터링을 통해 사용 가능한 모든 ActivityWatch 버킷을 나열합니다.

매개변수:

type (선택 사항): 버킷을 유형별로 필터링합니다(예: "window", "web", "afk")
includeData (선택 사항): 응답에 버킷 데이터를 포함합니다.

실행 쿼리

ActivityWatch의 쿼리 언어(AQL)로 쿼리를 실행합니다.

매개변수:

timeperiods : 문자열 배열 형식으로 쿼리할 기간을 지정합니다. 날짜 범위를 지정하려면 ["2024-10-28/2024-10-29"] 형식을 사용하세요.
query : ActivityWatch 쿼리 언어의 쿼리 명령문 배열, 각 항목은 세미콜론으로 구분된 명령문이 포함된 완전한 쿼리입니다.
name (선택 사항): 쿼리 이름(캐싱에 사용됨)

중요 : 각 쿼리 문자열에는 세미콜론으로 구분된 여러 문장이 포함된 완전한 쿼리가 포함되어야 합니다.

요청 형식 예:

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

참고사항:

timeperiods 슬래시를 사용하여 미리 형식화된 날짜 범위가 있어야 합니다.
query 배열의 각 항목은 모든 명령문을 포함하는 완전한 쿼리입니다.

이벤트 가져오기

ActivityWatch 버킷에서 원시 이벤트를 가져옵니다.

매개변수:

bucketId : 이벤트를 가져올 버킷의 ID
start (선택 사항): ISO 형식의 시작 날짜/시간
end (선택 사항): ISO 형식의 종료 날짜/시간
limit (선택 사항): 반환할 최대 이벤트 수

get-settings

서버에서 ActivityWatch 설정을 가져옵니다.

매개변수:

key (선택 사항): 모든 설정 대신 특정 설정 키를 가져옵니다.

쿼리 언어 예제

ActivityWatch는 간단한 쿼리 언어를 사용합니다. 다음은 몇 가지 일반적인 패턴입니다.

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

구성

서버는 기본적으로 http://localhost:5600 에서 ActivityWatch API에 연결합니다. ActivityWatch 인스턴스가 다른 호스트 또는 포트에서 실행 중인 경우 소스 코드에서 이를 수정할 수 있습니다.

문제 해결

ActivityWatch가 실행되지 않음

ActivityWatch가 실행 중이 아니면 서버에 연결 오류가 표시됩니다. ActivityWatch가 실행 중이고 http://localhost:5600 에서 접속 가능한지 확인하세요.

쿼리 오류

쿼리 오류가 발생하는 경우:

쿼리 구문을 확인하세요
버킷 ID가 올바른지 확인하세요
기간에 데이터가 포함되어 있는지 확인하세요
자세한 내용은 ActivityWatch 로그를 확인하세요.

Claude/MCP 쿼리 서식 문제

Claude가 이 MCP 서버를 통해 쿼리를 실행할 때 오류를 보고하는 경우, 서식 문제 때문일 가능성이 높습니다. 프롬프트에서 쿼리가 다음 형식을 정확히 따르는지 확인하세요.

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

일반적인 문제:

기간이 올바르게 형식화되지 않았습니다(배열 내의 단일 문자열에 "시작/종료"가 있어야 함)
쿼리 문은 하나의 문자열로 결합되는 대신 별도의 배열 요소로 분할됩니다.

가장 흔한 서식 문제

가장 흔한 오류는 Claude가 다음과 같이 각 쿼리 문을 자체 배열 요소로 분할할 때 발생합니다.

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

이는 잘못된 표현입니다. 대신 모든 명령문은 배열 내의 단일 문자열에 있어야 합니다.

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

클로드를 촉구할 때

클로드에게 질문할 때는 형식을 명확하게 설명하고 예시를 들어주세요. 예를 들어 다음과 같이 말할 수 있습니다.

"기간을 ["2024-10-28/2024-10-29"] 로 지정하고 쿼리를 ["statement1; statement2; RETURN = result;"] 로 실행하세요. 중요: 모든 쿼리 문이 배열 내 단일 문자열에 있어야 하며, 별도의 배열 요소로 분할되어서는 안 됩니다."

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

특허

MIT

You must be authenticated.

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

Tools

Claude와 같은 대규모 언어 모델이 Model Context Protocol을 통해 ActivityWatch 시간 추적 데이터와 상호 작용할 수 있도록 하는 인터페이스를 통해 애플리케이션 사용, 검색 기록 및 생산성 패턴에 대한 쿼리를 실행할 수 있습니다.

Related Resources

Reddit Discussion about this server

Appeared in Searches

A server for searching and accessing emails