Skip to main content
Glama
enesjakozh
8bitgentleman

ActivityWatch MCP Server

by 8bitgentleman
OverviewInspectSchemaRelated ServersScoreDiscussions
TypeScript
Local

ActivityWatch MCP 서버

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

특징

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

  • 쿼리 실행 : 강력한 AQL(ActivityWatch 쿼리 언어) 쿼리를 실행합니다.

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

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

Related MCP server: Claude MCP Data Explorer

설치

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

npm에서 설치(곧 제공)

지엑스피1

소스에서 빌드

  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(또는 다른 MCP 클라이언트)

용법

Claude와 함께 데스크톱 사용

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

  1. 데스크톱용 Claude를 다시 시작하세요

  2. 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 에서 접속 가능한지 확인하세요.

쿼리 오류

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

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

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

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

  4. 자세한 내용은 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

One-click Deploy
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/8bitgentleman/activitywatch-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server