ActivityWatch MCP Server

<p align="center"> <a href="./README.md">English</a> | <a href="./README_zh.md">中文</a> </p>

<h1 align="center">🔍 ActivityWatch MCP Server</h1>

<p align="center"> <strong>Let your AI companion see what you do, not just what you say.</strong> </p>

<p align="center"> <a href="https://github.com/JM-404/activitywatch-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a> <img src="https://img.shields.io/badge/Node-%3E%3D20-3C873A" alt="Node >= 20"> <img src="https://img.shields.io/badge/MCP-stdio-f4a261" alt="MCP stdio"> <a href="https://activitywatch.net/"><img src="https://img.shields.io/badge/ActivityWatch-compatible-7B68EE" alt="ActivityWatch"></a> </p>

---

An MCP server that gives AI assistants real-time awareness of your computer activity through ActivityWatch. No raw queries. No AQL syntax. Just ask your AI "what did I do today?" and get a human-readable answer.

Why this one?

There are other ActivityWatch MCPs out there. Here's how this one is different:

	This project	Others
Query interface	Pre-aggregated, high-level tools	Raw AQL queries
User needs to know AQL?	No	Yes
Built-in categories	✅ coding, browsing, communication, etc.	❌
Ready-to-use tools	get_day_summary, get_current_activity, etc.	run_query(aql_string)
Designed for	AI companions & chat interfaces	Developer debugging

TL;DR: Other MCPs give your AI a database console. This one gives your AI eyes.

What can your AI do with this?

Once connected, your AI companion can answer questions like:

• 🕐 "What am I working on right now?"
• 📊 "How did I spend my time today?"
• 💻 "How many hours did I code this week?"
• 🌙 "What time did I stop working last night?"
• 🔍 "Show me everything I did between 2pm and 5pm yesterday."
• 🌐 "What websites did I spend the most time on?"
• 📁 "Which projects did I work on this week?"
• 🏷️ "Add Cursor to my coding category."

Your AI knows what you do, not just what you say. It can notice patterns you miss — like when you've been coding for 5 hours straight without a break.

Quick Start

1. Prerequisites

• ActivityWatch installed and running
• Node.js >= 20

2. Install

git clone https://github.com/JM-404/activitywatch-mcp.git
cd activitywatch-mcp
npm install && npm run build

3. Configure

Add to your Claude Desktop / Claude Code MCP config:

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

4. Try it

Open Claude and ask: "What have I been doing on my computer today?"

That's it. No AQL. No bucket IDs. Just conversation.

Tools

get_current_activity

"What am I doing right now?"

Returns the currently active app, window title, duration, and AFK status.

get_day_summary

"How did I spend my time today?"

Top apps by usage time, total active/AFK hours, first and last active timestamps.

Parameters: date (optional, defaults to today)

get_category_time

"How many hours did I code this week?"

Aggregated time for a category or specific app over a date range, with daily breakdown.

Parameters: category (required), start_date, end_date (optional)

Built-in categories:

Category	Apps
coding	VS Code, PyCharm, Terminal, iTerm2, Cursor, Warp, Xcode
browsing	Chrome, Safari, Firefox, Arc, Edge
communication	WeChat, Slack, Discord, Telegram, Messages, Zoom, Teams
entertainment	Bilibili, YouTube, Spotify, Netflix
writing	Obsidian, Notion, Typora, Word, Pages
design	Figma, Sketch, Canva, Photoshop

Customize categories with AW_CATEGORIES_FILE env var pointing to your own JSON.

get_timeline

"Walk me through my afternoon."

Chronological list of app switches with window titles and durations.

Parameters: date, start_time, end_time, min_duration_seconds

get_browser_history

"What websites did I visit today?"

Top domains by time spent. Requires the ActivityWatch browser extension.

Parameters: date, domain (optional filter)

manage_categories

"Add Cursor to my coding category."

View and modify activity category mappings at runtime. Changes persist to ~/.activitywatch-mcp/categories.json.

Parameters: action (list | add | remove | update), category, apps

get_project_time

"Which projects did I work on this week?"

Coding time broken down by project/repository. Extracts project names from IDE window titles (VS Code, Cursor, PyCharm, Xcode, Terminal).

Parameters: start_date, end_date (optional)

Natural language dates

All date parameters accept natural language in addition to YYYY-MM-DD:

today, yesterday, this_week, last_week, this_month, last_month, last_7_days, last_30_days

Environment Variables

Variable	Default	Description
AW_HOST	http://localhost:5600	ActivityWatch API address
AW_TITLE_MAX_LENGTH	80	Truncate window titles for privacy
AW_CATEGORIES_FILE	built-in	Path to custom category mapping JSON

Privacy

🔒 Your data never leaves your machine.

• ActivityWatch stores everything locally
• This MCP server runs locally
• Data flows: ActivityWatch (local) → MCP Server (local) → Your AI conversation
• Window titles are truncated to prevent accidental exposure of sensitive content
• No telemetry, no external API calls, no cloud storage

Roadmap

• [ ] macOS Screen Time integration (iPhone + Mac data from knowledgeC.db)
• [ ] Auto-generated daily/weekly reports
• [ ] Proactive alerts (e.g., "You've been coding for 4 hours — take a break")
• [ ] Productivity scoring and trend analysis
• [ ] SSE transport for remote access

Contributing

PRs and issues welcome. If you have ideas for new tools or categories, open an issue.

License

MIT

---

<p align="center"> Built with ❤️ for the AI companion community.<br> <em>Because your AI should know you, not just answer you.</em> </p>