screentime-mcp

README

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:

• Accessing / Exporting Apple's Screen Time Data

• Using MacOS Screen Time data to create work hour reports

• How to Retrieve Screen Time Data on macOS via the Command Line

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 Tool Description and Generated SQL Views.

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 (also in the repo as mcp-config.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:")
  -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)
      --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).

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

Released under the MIT License, see LICENSE.txt.

---

Made with ❤ and 🔥 by the team behind AgentDank.

Documentation

Overview

Copyright 2025 Neomantra Corp