screentime-mcp by AgentDank - MCP Server

`screentime-mcp`

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 sql argument allowing the LLM to query the data. The result always comes back as a CSV, simplifying the handling for the LLM.

Screen Time SQLite Data
Installation
Using with LLMs
- Claude Desktop
- Ollama and mcphost
Command Line Usage
Building
Metadata
Contribution and Conduct
Credits and License

Screen Time SQLite Data

Your Screen Time data is stored on your MacOS computer in a SQLite database. Here's some references:

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.

The MCP Server exposes the following and .

Installation

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.

The following configuration JSON () sets this up:

{
    "mcpServers": {
      "screentime": {
        "command": "~/go/bin/screentime-mcp",
        "args": [
        ]
      }
    }
  }

Claude Desktop

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. **

For local inferencing, there are MCP hosts that support Ollama. You can use any Ollama LLM that supports "Tools". We experimented with mcphost, authored by the developer of the mcp-go library that peformed the heavy lifting for us.

Here's how to install and run with it with the configuration above, stored in mcp-config.json:

$ go install github.com/mark3labs/mcphost@latest
$ ollama pull llama3.3
$ mcphost -m ollama:llama3.3 --config mcp-config.json
...chat away...

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 ().

The --dev mode will reload the pre-flight migration file () 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.

Building

Building is performed with task:

$ 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 . 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 and the pre-flight . 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

Released under the MIT License, see .

Made with :heart: and :fire: by the team behind AgentDank.