lifeline-mcp

MCP server and CLI for Lifeline, the macOS productivity tracker.

Read your session history, break patterns, and pomodoro stats from any AI tool (Claude, Claude Code, ChatGPT) or the command line. Control Lifeline remotely: start and stop sessions, take breaks, log meetings.

Quick start

Installed directly from GitHub via npx. No separate npm registry package — the tool name lifeline-mcp is taken on npm by an unrelated project.

Claude Code (one command)

claude mcp add lifeline -- npx -y github:metztim/lifeline-mcp

That's it. Claude Code can now read your Lifeline data and control sessions.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lifeline": {
      "command": "npx",
      "args": ["-y", "github:metztim/lifeline-mcp"]
    }
  }
}

Restart Claude Desktop after saving.

Other AI tools

Any tool that supports the Model Context Protocol can use this server. Point it at npx -y github:metztim/lifeline-mcp.

CLI only

npm install -g github:metztim/lifeline-mcp

What you can do

Ask your AI tool about your work patterns

• "How many pomodoros did I complete this week?"
• "Show me my session history for today"
• "What's my average session length this month?"
• "When did I last take a break? How much break debt do I have?"
• "Compare my Monday and Friday productivity"
• "Which session labels do I use most?"

Control Lifeline from your AI tool

• "Start a 45-minute deep work session"
• "I'm going into a meeting with Nathan"
• "Stop my session"
• "Time for a break"

Use the CLI for quick checks

lifeline status                    # What's happening right now
lifeline summary                   # Today's stats
lifeline summary --week            # Past 7 days
lifeline summary --month           # Past 30 days
lifeline day                       # Today's full timeline
lifeline day 2026-03-15            # Specific day
lifeline sessions --week           # All sessions this week

Automate with the CLI

lifeline start "Deep work" --emoji 🧠 --duration 45
lifeline stop
lifeline break
lifeline meeting "Standup" --emoji 📞 --duration 30

MCP tools reference

Tool	Description
get_status	Current state, active session info, break debt, pomodoro count
get_day	Full day activity with timeline, milestones, active periods
get_range	Activity data for a date range
get_summary	Computed stats: work time, sessions, pomodoros, labels
start_session	Start a session (optional: title, emoji, duration, strict mode)
stop_session	Stop current session or meeting
start_break	Start a break
start_meeting	Start a meeting (optional: title, emoji, duration)

How it works

Reading data: Reads Lifeline's activity JSON files directly from the app's sandbox container (~/Library/Containers/com.saent.lifeline/). When macOS blocks that folder (recent macOS versions do, unless the app running the MCP server has Full Disk Access), it asks the running Lifeline app for the same history over AppleScript instead. No network requests and no API keys: your data stays local.

Controlling Lifeline: Write commands (start, stop, break, meeting) use AppleScript to communicate with the running Lifeline app. Lifeline must be running for these commands to work.

Requirements

• macOS
• Lifeline v1.8.0 or later (for AppleScript support)
• Node.js 18+ (for npx)

License

MIT