screentime-mcp-server

MCP server for querying macOS Screen Time data. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

Reads app usage data directly from macOS knowledgeC.db via sqlite3 CLI — no native modules or dependencies required.

Requirements

• macOS (Screen Time must be enabled)
• Node.js >= 18
• Full Disk Access must be granted to the host application (Claude Desktop, Terminal, etc.)

Granting Full Disk Access

1. Open System Settings → Privacy & Security → Full Disk Access
2. Add the application that runs the MCP server (e.g., Claude Desktop, Terminal, WezTerm)

This is required because knowledgeC.db is in a protected location.

Setup

Claude Code

claude mcp add screentime -- npx -y screentime-mcp-server

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "screentime": {
      "command": "npx",
      "args": ["-y", "screentime-mcp-server"]
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "screentime": {
      "command": "npx",
      "args": ["-y", "screentime-mcp-server"]
    }
  }
}

Tools

get_screentime

Get app usage data for a specific date with human-readable app names.

Parameters:

Parameter	Type	Default	Description
date	string	today	Date in YYYY-MM-DD format
min_seconds	number	60	Minimum usage duration in seconds

Example output:

# Screen Time: 2026-02-14

**Total: 5h 30m**

- WezTerm: 2h 15m
- Arc: 1h 30m
- Ableton Live: 55m
- Obsidian: 50m

## Hourly Breakdown

- **09:00**: WezTerm 45m, Arc 12m
- **10:00**: Ableton Live 55m
- **11:00**: WezTerm 40m, Arc 18m

## Timeline Detail

- 09:05-09:50 WezTerm (45m)
- 09:50-10:02 Arc (12m)
- 10:02-10:57 Ableton Live (55m)

screentime_sql

Run a custom SQL query directly against knowledgeC.db.

Parameters:

Parameter	Type	Description
sql	string	SQL query to execute

Schema notes:

• Table: ZOBJECT
• Filter: ZSTREAMNAME = '/app/usage'
• App bundle ID: ZVALUESTRING
• Timestamps use Core Data epoch (add 978307200 to convert to Unix timestamp)
• Use 'localtime' modifier for local timezone

App Name Resolution

Bundle IDs are resolved to human-readable names using:

1. Built-in dictionary (common apps like Safari, Chrome, VS Code, Slack, etc.)
2. mdfind + mdls lookup (finds any installed app)
3. Fallback: last component of bundle ID, capitalized

License

MIT