🔍 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:

	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

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

ActivityWatch MCP Server