RescueTime MCP Server

A Model Context Protocol (MCP) server for RescueTime - access productivity data, focus sessions, highlights, and activity tracking.

Features

Category	Tools	Description
Analytics	get_activity_data	Query activity data with flexible filters (date range, category, productivity level, device type)
	get_daily_summary	Last 2 weeks of daily productivity summaries with pulse scores
	get_productivity_score	Single-day productivity pulse and detailed breakdown
Focus	start_focus_session	Start focus mode (blocks distracting apps and sites)
	end_focus_session	End the current focus session
	get_focus_sessions	Recent focus session history
Highlights	get_highlights	Get logged highlights/accomplishments (Premium)
	post_highlight	Log a new highlight
Offline	log_offline_time	Log offline activities (meetings, breaks, up to 4 hours)

Quick Start

Option 1: NPX (No install required)

RESCUETIME_API_KEY=your_key npx rescuetime-mcp-server

Or add to your MCP config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "rescuetime": {
      "command": "npx",
      "args": ["rescuetime-mcp-server"],
      "env": {
        "RESCUETIME_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option 2: Claude Code

claude mcp add --transport stdio rescuetime -- npx rescuetime-mcp-server

Then set your API key in your environment or .env file.

Option 3: Install globally

npm install -g rescuetime-mcp-server
RESCUETIME_API_KEY=your_key rescuetime-mcp-server

Getting Your API Key

1. Go to https://www.rescuetime.com/anapi/manage
2. Create a new API key
3. Set it as the RESCUETIME_API_KEY environment variable

Environment Variables

Variable	Required	Description
RESCUETIME_API_KEY	Yes	RescueTime API key
TRANSPORT_TYPE	No	stdio (default) or httpStream
PORT	No	HTTP port when using httpStream (default: 3000)

Tool Details

get_activity_data

Query activity data with flexible filters. Returns time spent on activities, categories, or productivity levels.

Parameters:

• perspective — rank (default), interval, or member
• resolution — month, week, day (default), hour, or minute
• restrict_kind — activity (default), category, productivity, document, efficiency, or overview
• restrict_begin / restrict_end — Date range (YYYY-MM-DD)
• restrict_thing — Filter to specific activity or category name
• restrict_source_type — computers, mobile, or offline

get_daily_summary

Returns the last 2 weeks of daily productivity rollups. Each day includes:

• Productivity Pulse (0-100 score)
• Time breakdowns by productivity level (Very Productive through Very Distracting)
• Category percentages (Software Development, Communication, etc.)

get_productivity_score

Get the detailed productivity breakdown for a specific date (defaults to today).

start_focus_session

Start a RescueTime Focus Session that blocks distracting websites and apps.

Parameters:

• duration — Minutes (must be a multiple of 5, or -1 for until end of day)

post_highlight

Log an accomplishment or milestone. Premium feature.

Parameters:

• description — Highlight text (max 255 characters)
• highlight_date — Date (YYYY-MM-DD, defaults to today)
• source — Source label (defaults to "mcp-server")

log_offline_time

Log time spent away from the computer (meetings, breaks, etc.).

Parameters:

• start_time — ISO 8601 format with timezone (e.g., 2026-03-26T09:00:00-04:00)
• end_time — ISO 8601 format with timezone. Max 4 hours after start.
• activity_name — Short name (e.g., "Team Meeting", "Lunch Break")
• activity_details — Additional details (optional)

RescueTime API Notes

• Rate limits: 60 requests/minute, 1,000 requests/hour
• Data sync: Premium accounts sync every 3 minutes, Lite every 30 minutes
• Highlights & Alerts: Premium features
• Offline time: Max 4 hours per entry, no future dates

Development

pnpm install
pnpm validate        # format + lint + typecheck + test + build
pnpm inspect         # Build + launch MCP Inspector for interactive testing
pnpm dev             # Development build with watch mode

Architecture

Built with FastMCP, functype (IO, Option, Either, Try), and Zod.

• IO effects: API calls return IO<never, Error, T> — lazy, composable, with built-in retry/timeout
• IO.gen do-notation: Complex tool handlers use generator-based do-notation for readable effect composition
• Option singleton: Client lifecycle managed via Option<RescueTimeClient>
• Sealed errors: ApiError | ConfigError | RateLimitError with _kind discriminator

License

MIT

---

Sponsored by SapientsAI — Building agentic AI for businesses