ActivityWatch MCP 서버

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

기능

• 버킷 목록: 사용 가능한 모든 ActivityWatch 버킷 보기

• 쿼리 실행: 강력한 AQL(ActivityWatch Query Language) 쿼리 실행

• 원시 이벤트 가져오기: 모든 버킷에서 직접 이벤트 검색

• 설정 가져오기: ActivityWatch 구성 설정에 액세스

Related MCP server: Paprika SQL MCP Server

설치

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

npm을 통한 설치 (곧 제공 예정)

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

# Or install locally
npm install activitywatch-mcp-server

소스에서 빌드

1. 이 저장소를 복제합니다:

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

2. 종속성을 설치합니다:

   npm install

3. 프로젝트를 빌드합니다:

   npm run build

사전 요구 사항

• ActivityWatch가 설치되어 실행 중이어야 함

• Node.js (v14 이상)

• Claude for Desktop (또는 기타 MCP 클라이언트)

사용법

Claude for Desktop과 함께 사용하기

1. Claude for Desktop 구성 파일을 엽니다:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. MCP 서버 구성을 추가합니다:

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

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

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

3. Claude for Desktop을 다시 시작합니다

4. Claude 인터페이스에서 MCP 아이콘을 찾아 작동하는지 확인합니다

Linux에서 Gemini CLI와 함께 rootless podman 컨테이너 사용하기

먼저 다음 명령어로 이미지를 빌드하세요:

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

이 예제는 Activity Watch를 127.0.0.1에서 사용할 수 없는 경우에 대한 오버라이드를 사용합니다(다음 섹션 참조). 필요하지 않은 경우 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"
 }
 }
 }
}

ActivityWatch 서버 호스트/포트 재정의

예를 들어 컨테이너 내부와 같이 Windows Subsystem for Linux(WSL) 내에서 이 MCP 서버를 실행하려는 경우, Windows에서 실행 중인 AW 서버는 127.0.0.1에서 사용할 수 없습니다. 표준 localhost 연결을 재정의하려면 아래와 같이 AW_API_BASE 환경 변수나 --aw-api-base 플래그를 사용하세요:

# 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

참고: AW 서버는 연결에 사용되는 이름에 민감할 수 있지만, 실행 중인 컴퓨터 이름에 .local 접미사가 붙은 이름은 허용합니다.

쿼리 예시

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

• 모든 버킷 나열: "내가 가진 ActivityWatch 버킷은 무엇인가요?"

• 애플리케이션 사용 요약 가져오기: "오늘 가장 많이 사용한 애플리케이션을 보여줄 수 있나요?"

• 브라우징 기록 보기: "오늘 가장 많은 시간을 보낸 웹사이트는 어디인가요?"

• 생산성 확인: "오늘 생산성 앱에서 보낸 시간은 얼마나 되나요?"

• 설정 보기: "내 ActivityWatch 설정은 무엇인가요?" 또는 "ActivityWatch에서 특정 설정을 확인할 수 있나요?"

사용 가능한 도구

list-buckets

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

매개변수:

• type (선택 사항): 유형별로 버킷 필터링 (예: "window", "web", "afk")

• includeData (선택 사항): 응답에 버킷 데이터 포함

run-query

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 배열의 각 항목은 모든 문장이 포함된 완전한 쿼리여야 합니다.

get-events

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가 실행 중이지 않으면 서버에 연결 오류가 표시됩니다. ActivityWatch가 실행 중이며 지정된 호스트/포트 주소(http://localhost:5600, 재정의하지 않은 경우)에서 액세스할 수 있는지 확인하세요.

쿼리 오류

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

1. 쿼리 구문을 확인하세요.

2. 버킷 ID가 올바른지 확인하세요.

3. 기간(timeperiods)에 데이터가 포함되어 있는지 확인하세요.

4. 자세한 내용은 ActivityWatch 로그를 확인하세요.

Claude/MCP 쿼리 형식 문제

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

{
 "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;"]
}

Claude에게 프롬프트할 때

Claude에게 프롬프트할 때는 형식을 매우 명확하게 지정하고 예시를 사용하세요. 예를 들어 다음과 같이 말하세요:

"timeperiods를 ["2024-10-28/2024-10-29"]로, query를 ["statement1; statement2; RETURN = result;"]로 설정하여 쿼리를 실행해 줘. 중요: 모든 쿼리 문은 별도의 배열 요소로 분할하지 말고 배열 내의 단일 문자열로 작성해야 해."

기여

기여를 환영합니다! 자유롭게 Pull Request를 제출해 주세요.

라이선스

MIT

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• activitywatch_get_eventsC
• activitywatch_get_settingsB
• activitywatch_list_bucketsB
• activitywatch_query_examplesB
• activitywatch_run_queryC