🔍 ActivityWatch MCP Server

English | 中文

🔍 ActivityWatch MCP Server

Let your AI companion see what you do, not just what you say.

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:

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:

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

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

Built with ❤️ for the AI companion community. Because your AI should know you, not just answer you.