Advanced Feature

CLI & MCP

Query your local time.md database from the terminal or connect it to MCP-compatible coding agents for natural-language screen-time analysis.

Local read access

The CLI and MCP server read local SQLite databases on demand. They do not upload your activity data to time.md.

Review boundaries

Install the CLI

Open Settings → CLI Access and choose install. time.md creates symlinks in your user-writable bin directory:

~/.local/bin/timemd
~/.local/bin/timemd-mcp

timemd is the primary command. timemd-mcp remains available for backwards compatibility and for explicit MCP-server use.

If ~/.local/bin is not on your shell PATH, add it with the snippet shown by the app:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
Conflict handling: if another file already exists at ~/.local/bin/timemd or timemd-mcp, remove it or choose a different install approach before retrying.

CLI commands

The CLI prints JSON to stdout. Tool aliases omit the get_ prefix, so top-apps resolves to get_top_apps.

timemd today --limit 5

timemd top-apps --since 7d --limit 20

timemd sessions --since today --app-name Slack --limit 50

timemd call get_heatmap --since 30d --stream-type app_usage

timemd list-tools
Pattern Meaning
timemd <alias> [opts] Run a tool by friendly alias, such as today or top-apps.
timemd call <tool> [opts] Run an exact MCP tool name, such as get_daily_trend.
timemd list-tools Print the available tool catalog as JSON.
timemd mcp Start the stdio MCP server explicitly.

Date arguments accept values such as today, yesterday, 7d, 30d, this_week, this_month, this_year, all, and ISO dates such as 2026-06-06.

Read-only SQL

The sql and query commands call the raw_query tool. Only a single read-only statement is allowed, and it must start with SELECT, WITH, or EXPLAIN. Semicolons are rejected.

timemd sql 'SELECT app_name, SUM(duration_seconds) AS seconds FROM usage GROUP BY app_name ORDER BY seconds DESC LIMIT 10'

timemd sql 'SELECT word, SUM(count) AS total FROM inp.typed_words GROUP BY word ORDER BY total DESC LIMIT 25'

When present, the helper attaches sibling databases:

  • cat.app_category_map from category-mappings.db.
  • inp.keystroke_events, inp.mouse_events, inp.typed_words, and inp.cursor_heatmap_bins from input-tracking.db.

MCP setup

The bundled binary is a standard stdio MCP server. In Settings → MCP Integration, time.md can register a mcpServers.timemd entry for supported agents while preserving the rest of each config file.

Agent Config path What time.md writes
Claude Code ~/.claude.json mcpServers.timemd
Cursor ~/.cursor/mcp.json mcpServers.timemd
Windsurf ~/.codeium/windsurf/mcp_config.json mcpServers.timemd

For any other MCP-compatible tool, copy the generic snippet from the MCP settings screen. It points to the bundled timemd-mcp executable inside the app bundle. The exact path depends on where time.md is installed.

{
  "mcpServers": {
    "timemd": {
      "command": "/Applications/time.md.app/Contents/Resources/timemd-mcp",
      "args": [],
      "env": {}
    }
  }
}

Available tools

The catalog includes summary, trend, session, category, web/media, heatmap, comparison, and input-tracking tools. Use get_schema or timemd list-tools first when you are unsure what is available in your build.

Core summaries

get_today, get_range_totals, get_top_apps, get_top_categories, get_sessions.

Time patterns

get_hourly_distribution, get_daily_trend, get_weekday_breakdown, get_heatmap, get_typical_day.

Deep analysis

get_app_detail, get_longest_sessions, get_context_switches, get_app_transitions, compare_periods.

Input tracking

get_cursor_heatmap, get_top_typed_words, get_top_typed_keys, get_typing_intensity, get_input_event_counts.

Input tools return empty results when optional input tracking was never enabled or the relevant tables do not exist.

Global toggle and tool gating

MCP access can be controlled from time.md settings and by environment variables.

Control Effect
Global MCP toggle When off, the server returns no tools and rejects tool calls.
Per-tool toggles Disabled tools are filtered from tools/list and rejected on tools/call.
TIMEMD_MCP_ENABLED=0 Disables the server from an agent config or shell environment.
TIMEMD_DISABLED_TOOLS Comma-separated tool names to hide, for example raw_query,get_top_typed_words.
mcp-settings.json Runtime settings file written under Application Support so manual agent configs can still observe time.md’s settings. 
TIMEMD_DISABLED_TOOLS=raw_query,get_top_typed_words timemd list-tools

TIMEMD_MCP_ENABLED=0 timemd-mcp mcp

Data paths and overrides

The helper searches for the canonical local data directory and a few legacy/development locations. The default location is:

~/Library/Application Support/time.md/screentime.db

Environment overrides are available for development and diagnostics:

Variable Meaning
TIMEMD_DATA_DIR Directory containing screentime.db and sibling databases.
SCREENTIME_DB_PATH Exact path to the main SQLite database.
TIMEMD_MCP_SETTINGS_PATH Alternate path for the runtime MCP settings JSON file.

Privacy boundaries

  • The CLI and MCP server read local SQLite files on demand; time.md does not receive those query results.
  • Agents connected through MCP can see any data returned by enabled tools. Disable sensitive tools before connecting agents you do not fully trust.
  • raw_query is read-only, but it can still reveal detailed local data, including input-tracking tables if they exist.
  • Input-tracking tools may expose words, key counts, cursor positions, and event intensity if you enabled that feature locally.
  • Removing the mcpServers.timemd entry from an agent config disconnects that agent. Turning off the global MCP toggle disables all MCP access from time.md settings.

For the full local-data model, see Privacy & Local Data.