Screen Time Exporter
Apple Screen Time from your iPhone, iPad and Mac — in your own database, Grafana, Home Assistant and AI assistant. One small background agent on your Mac. No cloud service, no account, no ActivityWatch server.
エージェントを強化
公開元からインストールします。PlugMCP のエンドポイントではありません。
リモート URL か、手元のマシンのコマンドか 2 つのインストール方法の違い
PlugMCP で実行
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
起動公開元より
Apple Screen Time from your iPhone, iPad and Mac — in your own database, Grafana, Home Assistant and AI assistant. One small background agent on your Mac. No cloud service, no account, no ActivityWatch server.
Apple Screen Time from iPhone, iPad and Mac in your own database: SQLite, InfluxDB and Grafana, Home Assistant and MCP.
Website • Overview • Features • Screenshots • Quick start • Command line • AI assistants • How it works • Docs
Apple shows Screen Time on each device, for a week or two, and nowhere else. You cannot keep it, query it, chart it next to other data or trigger anything from it. Yet every Mac signed in to your Apple Account already receives the app usage of your iPhone and iPad through iCloud.
Screen Time Exporter reads those stores on the Mac — Biome for iPhone and iPad, knowledgeC.db for the Mac itself — every 15 minutes. It keeps every session in a local SQLite database, names and categorises the apps, and passes the result on to InfluxDB and Grafana, Home Assistant, the terminal, or an AI assistant over MCP.
The project stays deliberately:
knowledgeC.db through a temporary copy) and never writes to them.Unofficial hobby project. Not affiliated with Apple — see Disclaimer.
screentime summary for a week, day or range, as text, Markdown or JSON; screentime dump as CSV or JSON.screentime setup finds devices, tests the connections, writes the config and installs the agent; screentime doctor explains what is wrong.All screenshots use the synthetic data from scripts/demo_data.py.
uv tool install plus the setup wizard is the recommended path.
Requirements:
curl -LsSf https://astral.sh/uv/install.sh | sh). It brings its own Python 3.11+.uv tool install git+https://github.com/nichtlegacy/screentime
screentime setup # devices, InfluxDB, Home Assistant, launchd agent
screentime doctor # every check should say OK
screentime summary --day # today in the terminal
Expected: screentime setup lists your iPhone, iPad and Mac, runs a first sync and installs the launchd agent io.github.nichtlegacy.screentime, which syncs every 15 minutes.
Apple's stores are protected. Give Full Disk Access (System Settings → Privacy & Security → Full Disk Access) to your terminal for setup and to the Python interpreter that screentime setup prints for the background agent — why two.
docker/docker-compose.yml runs InfluxDB 2.7 and Grafana 12 with the datasource and the dashboard provisioned:
cp docker/.env.example docker/.env # set INFLUX_TOKEN and both passwords
docker compose -f docker/docker-compose.yml --env-file docker/.env up -d
Grafana listens on port 3000 (GRAFANA_PORT), InfluxDB on 8086 (INFLUX_PORT). Give screentime setup the InfluxDB URL, the token, org home and bucket screentime. For an existing Grafana, add an InfluxDB datasource with the Flux query language and import grafana/dashboards/screentime.json; the dashboard asks for the datasource and bucket.
The dashboard's "today" and "last 7 days" use the browser's time zone, which should match the exporter's
timezone.
Create a long-lived access token (Profile → Security) and give it to screentime setup with your Home Assistant URL. The sensors appear after the next sync:
Attributes, the limits of REST states, example automations and a dashboard card: docs/home-assistant.md.
v2 replaces the CSV, .env and aw-import-screentime with one installed tool. The v1 Home Assistant entity ids stay. Steps: docs/migration.md.
Options and the JSON shape: docs/cli.md.
screentime mcp is a read-only Model Context Protocol server over the local database. The MCP SDK is an optional extra:
uv tool install --force "screentime-exporter[mcp] @ git+https://github.com/nichtlegacy/screentime"
claude mcp add -s user screentime -- screentime mcp # Claude Code
For Claude Desktop, add this to ~/Library/Application Support/Claude/claude_desktop_config.json (use the path from which screentime):
{
"mcpServers": {
"screentime": { "command": "/Users/you/.local/bin/screentime", "args": ["mcp"] }
}
}
Codex, Cursor and other clients: docs/mcp.md.
Try: "How much screen time did I have last week compared to the week before?" or "Was I on my phone after midnight this week?"
A coding agent with terminal access can run the whole setup; you only flip the Full Disk Access switches and enter tokens yourself. The prompt to paste is in docs/agent-installation.md.
flowchart LR
subgraph phone["iPhone · iPad"]
st["Screen Time<br/>Share Across Devices"]
end
subgraph mac["Mac · launchd every 15 min"]
biome[("Biome App.InFocus<br/>iPhone · iPad")]
kc[("knowledgeC.db<br/>this Mac")]
run["screentime run<br/>src/screentime/"]
db[("SQLite<br/>screentime.db")]
end
st -->|"iCloud"| biome
biome --> run
kc --> run
run -->|"sessions + daily aggregates"| db
names["Installed Mac apps · App Store<br/>unknown bundle ids"] -.->|"name, category"| run
db -->|"changed days"| influx[("InfluxDB 2")]
influx --> grafana["Grafana<br/>grafana/dashboards/"]
db -->|"REST states"| ha["Home Assistant"]
db -->|"read-only"| cli["summary · dump"]
db -->|"read-only, stdio"| mcp["screentime mcp"]
mcp --> ai["Claude · Codex · Cursor"]
sources/biome.py parses the SEGB files of the App.InFocus stream, sources/knowledgec.py reads /app/usage from a temporary copy of knowledgeC.db. Each keeps its own cursor in SQLite.[apps] section renames stored sessions on the next run.summary, dump and the MCP server open the database read-only.Details: architecture, InfluxDB schema, taxonomy.
screentime setup writes ~/.config/screentime/config.toml (mode 0600). Every key is optional; config.example.toml lists them all.
Data lives in ~/Library/Application Support/screentime/, logs in ~/Library/Logs/screentime/. To remove everything: screentime setup --uninstall --purge, then uv tool uninstall screentime-exporter.
src/screentime/
├── sources/ # biome.py (iPhone, iPad), knowledgec.py (Mac)
├── _vendor/ccl_segb/ # SEGB reader from ccl-segb, unchanged
├── importer.py # sessions into SQLite
├── taxonomy.py # app names: apps.json, your config, installed apps, App Store
├── aggregates.py # daily, per-app, per-category and night splits
├── influx.py # InfluxDB export
├── homeassistant.py # Home Assistant sensors
├── queries.py # read-only queries for summary, dump and MCP
├── report.py # summary and dump
├── mcp_server.py # MCP tools and resource
├── wizard.py # screentime setup
├── launchd.py # launchd agent
├── health.py # screentime doctor
└── data/ # apps.json (names, categories), models.json (device models)
grafana/ # dashboard and provisioning
docker/ # InfluxDB + Grafana compose file
scripts/ # demo data generator, landing page build
site/ # landing page, deployed to GitHub Pages
docs/ # everything beyond this page
The landing page is screentime.nichtlegacy.com. Everything beyond this page is in docs/: setup, migration from v1, command line, app names, Home Assistant, MCP, agent installation, architecture. Release notes: CHANGELOG.md.
Everything stays on your Mac unless you configure a sink. Unknown apps are first looked for on the Mac itself; only bundle ids it cannot name go to Apple's public iTunes Lookup API, together with the storefront country. Turn that off with [lookup] enabled = false. The MCP server reads the local database; what your assistant sends to its model is up to the assistant. Tests and screenshots use synthetic data only.
No route to host (details).screentime doctor tells you the new path.unique_id and vanish on restart until the next sync, at most 15 minutes later (workaround).[apps].Issues and pull requests are welcome, especially app names for apps.json. Checks and guidelines: CONTRIBUTING.md.
MIT.
Screen Time Exporter is an unofficial, independent hobby project. It is not affiliated with, endorsed by, sponsored by, or connected to Apple Inc. in any way.
"Apple", "Screen Time", "iPhone", "iPad", "Mac", "macOS" and "iCloud" are trademarks of Apple Inc., used here only to describe the data the project reads. It reads files that macOS keeps on your own Mac; it does not use private APIs over the network.
Apple Screen Time from iPhone, iPad and Mac in your own database: SQLite, InfluxDB and Grafana, Home Assistant and MCP.
ツール
ツール一覧はまだありません。リモートサーバーは、最初のヘルスチェック後に取得されます。
よくある質問
このページで Cursor、Claude Desktop、Claude Code、VS Code 用の stdio 設定をコピーできます。PlugMCP のプロキシではなく、公開元のインストール方法を使います。
このレコードに必須の環境変数は記載されていません。
Screentime は stdio 経由でローカル実行されます。
最終チェックは 2026-10-28 です。 Apple Screen Time from iPhone, iPad and Mac in your own database: SQLite, InfluxDB and Grafana, Home Assistant and MCP.