screentime-mcp is a Model Context Procotol (MCP) server that respond to questions about your MacOS Screen Time. It is brought to you by AgentDank for educational purposes.
This MCP server loads that into a DuckDB database and exposes that database as an endpoint called screentime_sql. That endpoint takes a argument allowing the LLM to query the data. The result always comes back as a CSV, simplifying the handling for the LLM.
Currently, this is sensitive data, so you must enable "Full Disk Permissions" for the host environment of this MCP server. It runs on your computer, as it reads the local database file.
While we'd like to have pre-built binaries and Homebrew packages, we're having an issue with that right now. So the preferred way to install is using go install or building from source:
$ go install github.com/AgentDank/screentime-mcp@latest
It will be installed in your $GOPATH/bin directory, which is often ~/go/bin.
Using with LLMs
To use this screentime-mcp MCP server, you must configure your host program to use it. We will illustrate with Claude Desktop. We must find the screentime-mcp program on our system; the example below shows where screentime-mcp is installed with my go install.
Using Claude Desktop, you can follow their configuration tutorial but substitute the configuration above. With that in place, you can ask Claude question and it will use the screentime-mcp server.
PROBLEMO: To get this to work, you need to grant "Full Disk Access" to Claude Desktop (Claude.app) . What's the worst that can happen?!? The ScreenTime knowledgeC.db file is protected otherwise.
Ollama and mcphost
**I'm currently having issues with this working well, but leaving instructions for those interested. **
Similarly, you may need to grant your terminal application "Full Disk Access". Be careful out there.
Command Line Usage
Here is the command-line help:
usage: ./bin/screentime-mcp [opts]
--db string DuckDB data file to use, use ':memory:' for in-memory. Default is ':memory: (default ":memory:")
-d, --dev Activate dev mode
-h, --help Show help
-l, --log-file string Log file destination (or MCP_LOG_FILE envvar). Default is stderr
-j, --log-json Log in JSON (default is plaintext)
-o, --once Exit after one tool call
--sse Use SSE Transport (default is STDIO transport)
--sse-host string host:port to listen to SSE connections
-v, --verbose Verbose logging
To see what the MCP schema looks like, you can run task stdio-schema | jq (link).
The --dev mode will reload the pre-flight migration file (./internal/db/duckdb_views.sql) into a new DuckDB database on each tool call. This causes the MCP server to lose any DB state and try out a fresh migration without needing a re-build. It will also allow the MCP server to start with a failed migration.
The --once flag will only allow an MCP server to hadle one tool call. It literally os.Exit the MCP server after a short timeout. This is also useful for development.
$ task
task: [build] go build -o screentime-mcp main.go
Contribution and Conduct
Pull requests and issues are welcome. Or fork it. You do you.
Either way, obey our Code of Conduct. Be shady, but don't be a jerk.
Metadata
I was inspired to create this after reading a HackerNews comment in a thread about an Apple Health MCP Server. A high school researcher introduced me to the available ScreenTime sqlite data, as he used it in his attention/performance-tracking project. As I note on that thread:
I’ve found good value in making purpose-build MCP servers like that with the general model: Data<>DuckDB<>MCP<>LLM With verbose description for the LLM of an “sql” tool endpoint for it to use to explore.
I have since been using Claude to help improve the raw tool. This involves improving the Tool Description and the pre-flight SQL View Creation. I ask Claude to do some work with the tool, look at the problems it had with it (e.g. DuckDB dialect issues, timestamp conversion) and create changes. Since it knows the view and the tool description, it can do much of the heavy lifting itself, with a human guiding it along (mostly as a piece of meat restarting Claude Desktop).
Credits and License
Copyright (c) 2025 Neomantra Corp. Authored by Evan Wies for AgentDank, based on the dank-mcp codebase.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Screentime?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Screentime einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet Screentime?
Screentime läuft lokal über stdio.
Wann wurde Screentime zuletzt geprüft?
Zuletzt geprüft: 2026-10-27. SQL-based MCP server for Apple Screen Time