screentime-mcp

screentime-mcp 是一个响应关于您的 MacOS 屏幕时间 的问题的 Model Context Protocol (MCP) 服务器。它由 AgentDank 提供，用于教育目的。

此 MCP 服务器将数据加载到 DuckDB 数据库中，并将其作为名为 screentime_sql 的端点公开。该端点接受一个 sql 参数，允许大型语言模型查询数据。结果始终以 CSV 格式返回，简化了大型语言模型的数据处理。

---

• 屏幕时间 SQLite 数据
• 安装
• 与大型语言模型一起使用
  • Claude Desktop
  • Ollama 和 mcphost
• 命令行使用
• 构建
• 元数据
• 贡献和行为准则
• 致谢和许可

屏幕时间 SQLite 数据

您的屏幕时间数据存储在 MacOS 计算机上的 SQLite 数据库中。以下是一些参考资料：

• 访问/导出 Apple 屏幕时间数据

• 使用 MacOS 屏幕时间数据创建工作小时报告

• 如何通过命令行检索 macOS 上的屏幕时间数据

目前，这些是敏感数据，因此您必须为此 MCP 服务器的主机环境启用“完全磁盘权限”。它运行在您的计算机上，因为它读取本地数据库文件。

MCP 服务器公开了以下工具描述和生成的 SQL 视图。

安装

虽然我们希望有预构建的二进制文件和 Homebrew 包，但我们现在遇到了一些问题。因此，首选的安装方式是使用 go install 或从源代码构建：

$ go install github.com/AgentD.ank/screentime-mcp@latest

它将被安装在您的 $GOPATH/bin 目录中，通常是 ~/go/bin。

与大型语言模型一起使用

要使用此 screentime-mcp MCP 服务器，您必须配置您的主机程序来使用它。我们将使用 Claude Desktop 进行演示。我们必须找到系统中的 screentime-mcp 程序；下面的示例显示了 screentime-mcp 使用我的 go install 安装的位置。

以下配置 JSON（也在仓库中作为 mcp-config.json 存在）设置了这一点：

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

Claude Desktop

使用 Claude Desktop，您可以按照他们的配置教程进行操作，但替换上述配置。有了这个设置，您可以向 Claude 提问，它将使用 screentime-mcp 服务器。

问题： 要使这正常工作，您需要授予 Claude Desktop (Claude.app) “完全磁盘访问”。最坏的情况会怎样？屏幕时间的 knowledgeC.db 文件否则会被保护。

Ollama 和 mcphost

我目前正在遇到一些问题，但为了有兴趣的人留下说明。

对于本地推理，有一些支持 Ollama 的 MCP 主机。您可以使用任何支持“工具”的 Ollama LLM。我们尝试了由 mcp-go 库的作者编写的 mcphost，该库为我们做了大量的工作。

以下是使用上述配置安装和运行的方法，配置存储在 mcp-config.json 中：

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

同样，您可能需要授予您的终端应用程序“完全磁盘访问”。小心行事。

命令行使用

这里是命令行帮助：

用法：./bin/screentime-mcp [选项]

      --db 字符串         要使用的 DuckDB 数据文件，使用 ':memory:' 表示内存。默认值是 ':memory:' (默认 ":memory:")
  -d, --dev               激活开发模式
  -h, --help              显示帮助
  -l, --log-file 字符串   日志文件目标（或 MCP_LOG_FILE 环境变量）。默认值是 stderr
  -j, --log-json          使用 JSON 格式记录日志（默认是纯文本）
  -o, --once              在一次工具调用后退出
      --sse               使用 SSE 传输（默认是 STDIO 传输）
      --sse-host 字符串   监听 SSE 连接的 host:port
  -v, --verbose           详细日志

要查看 MCP 架构的样子，您可以运行 task stdio-schema | jq（链接）。

--dev 模式会在每次工具调用时将预飞行迁移文件（./internal/db/duckdb_views.sql）重新加载到一个新的 DuckDB 数据库中。这会导致 MCP 服务器丢失任何数据库状态并尝试进行新的迁移而无需重新构建。它还将允许 MCP 服务器在迁移失败的情况下启动。

--once 标志只允许 MCP 服务器处理一次工具调用。它会在短暂超时后实际 os.Exit MCP 服务器。这对于开发也很有用。

构建

构建使用 task：

$ task
task: [build] go build -o screentime-mcp main.go

---

贡献和行为准则

欢迎提交拉取请求和问题。或者分叉它。您做您自己。

无论如何，请遵守我们的行为准则。可以阴暗，但不要粗鲁。

元数据

在阅读了一篇关于 Apple Health MCP 服务器 的 HackerNews 评论 后，我受到启发创建了这个。一位高中研究员向我介绍了可用的屏幕时间 SQLite 数据，因为他将其用于他的注意力/性能跟踪项目。正如我在那条评论中提到的：

我发现制作像这样的特定用途的 MCP 服务器很有价值，其通用模型是：数据 <> DuckDB <> MCP <> 大型语言模型。为大型语言模型提供详细的“sql”工具端点描述，以便它可以用来探索。

此后，我一直在使用 Claude 来改进原始工具。这包括改进工具描述和预飞行SQL 视图创建。我让 Claude 使用该工具做一些工作，看看它遇到的问题（例如 DuckDB 方言问题、时间戳转换），并创建更改。由于它知道视图和工具描述，它可以自己完成大部分繁重的工作，人类只需引导它（主要是作为一块肉重启 Claude Desktop）。

致谢和许可

版权所有 © 2025 Neomantra Corp. 由 Evan Wies 为 AgentDank 编写，基于 dank-mcp 代码库。

根据 MIT 许可证发布，参见 LICENSE.txt。

---

由 AgentDank 团队用心和热情打造。