Skip to main content
Glama
deenjakoruzh
rankin-works

Vetroscope MCP

by rankin-works
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

Vetroscope MCP

一个用于 Vetroscope 的只读 模型上下文协议 服务器 — 为 LLM（Claude Desktop、Claude Code、ChatGPT、Cursor 等）提供有关您如何度过时间、参与过哪些项目以及目标完成进度的上下文。

直接以只读方式读取本地 Vetroscope SQLite。无云端往返、无需认证、可离线工作。

工具

报告与细分

工具

功能

get_report

某段时间的汇总报告 — 总活跃秒数、热门应用、带子项目嵌套的热门项目（YouTube 视频、SoundCloud 歌曲、Netflix 剧集）。

get_app_breakdown

单个应用在一段时间内按项目细分的报告，包含子项目。

get_app_stats

单个应用的深度统计：累计总数、活跃天数、每日序列、小时分布、星期分布。

get_tag_breakdown

单个标签的时间花费报告 — 热门应用、热门项目、每日序列、活跃/被动拆分。include_descendants 可汇总父标签的子树。

get_tag_stats

单个标签的深度统计（与 get_app_stats 对应）：累计总数、活跃天数、每日序列、小时和星期分布，以及标签的父级和子级（含汇总总数）。传入 include_descendants 可将父标签的整个子树汇总到序列中。

get_calendar

任意时间段的密集每日序列（热力图数据）— 默认为一整年。

get_device_breakdown

在多个设备上运行 Vetroscope 时，按设备统计的总数。

get_music_split

音乐与工作分析：边工作边听音乐 / 仅听音乐 / 专注工作 / 其他，以及按来源（Spotify、SoundCloud 等）统计的重叠总数。分类器可在每次调用时覆盖。

get_category_breakdown

将时间汇总到 Vetroscope 活动类别（coding、creative、productivity、communication、entertainment、music、gaming、browsing、system、other）— 与图表/设置中的分类法相同。

get_listening_history

原生音乐应用和浏览器音乐网站上的热门曲目和艺术家，以及每日收听分钟数。艺术家从“艺术家 — 曲目”子项目约定中解析。

get_media_links

Vetroscope 捕获的您实际播放过的媒体的规范深层链接 — Spotify spotify:track:… URI 和 YouTube youtube.com/watch?v=… URL — 与匹配的时间数据关联。需要 Vetroscope ≥ 0.2.30 并启用 capture_media_links。

get_focus_heatmap

7×24 的活跃前台秒数网格 — 您通常在什么时间进行特定类型的工作。可选的 app / project / tag 过滤器可缩小到单个活动；include_descendants 可汇总父标签的子树。

参考 / 查询

工具

功能

list_tags

您的标签，包含 id、名称、颜色、置顶标志、归档标志，以及嵌套标签的 parentId/parentName。默认隐藏已归档标签（传入 include_archived 显示）。

list_categories

活动类别分类法（id、标签、颜色）— coding、creative、productivity 等。

list_projects

所有曾跟踪的（应用、项目）对，包含累计总数 + 首次/最后出现时间 + 可选的子字符串搜索。

list_markers

您的时间线标记（时间戳、标签、颜色、图标、可选的区域结束时间）。

list_notes

您的笔记（标题、markdown 风格正文摘录，支持项目符号、粗体/斜体/@提及、可选时间戳/区域、置顶、文件夹）。可选的 folder 过滤器（UUID、名称或 none）。

list_note_folders

嵌套笔记文件夹（uuid、name、parentUuid、path、color）。

list_reminders

已配置的一次性、重复、间隔和标签阈值提醒。默认隐藏已禁用的提醒（传入 include_disabled 包含）。

list_reminder_events

提醒通知历史记录，可按时间段、未读状态或提醒 UUID 过滤。

活动 / 状态

工具

功能

get_sessions

连续活动块（开始/结束/持续时间）— 回答“我今天早上做了什么”的自然粒度。

get_current_status

最近一条记录 — 当前正在使用哪个应用/项目、多久前、跟踪中还是空闲。

query_entries

原始 30 秒条目的过滤列表（应用 / 项目 / 标签 / 搜索 / 时间段 / 模式）。

目标

工具

功能

get_goals_progress

已配置的应用 / 总体 / 标签目标的当前进度。

get_goal_achievements

您每天达成哪些目标的历史记录 — 用于回答连续达成问题。

所有时间感知工具都接受以下共享过滤器：

参数

用途

period

today · yesterday · week · month · year · 单个日期 YYYY-MM-DD · 包含范围的 YYYY-MM-DD..YYYY-MM-DD

hour_start / hour_end

本地时间的小时过滤器（含头不含尾）（例如 9 和 17 = 工作时间）

weekdays

星期整数数组（0=周日，1=周一，…，6=周六）。仅工作日传入 [1,2,3,4,5]。

device

current（本地机器）、来自 get_device_breakdown 的设备 UUID，或平台名称（darwin、win32、browser-extension）。省略则包括所有设备。

每个总数都分为活跃前台时间和被动离开收听时间（例如空闲时后台播放音乐），与仪表盘的区分一致。

Related MCP server: SQLite MCP Server

要求

  • 已安装 Vetroscope 并至少运行一次。

  • Node.js 18+。

安装

npx vetroscope-mcp

就这样 — 无需全局安装。首次运行将从 npm 获取包。

配置您的客户端

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "vetroscope": {
      "command": "npx",
      "args": ["-y", "vetroscope-mcp"]
    }
  }
}

重新启动 Claude Desktop。

Claude Code

claude mcp add vetroscope -- npx -y vetroscope-mcp

ChatGPT（开发者模式）

在连接器部分，添加一个新的 MCP 服务器，命令为 npx，参数为 -y vetroscope-mcp。

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "vetroscope": {
      "command": "npx",
      "args": ["-y", "vetroscope-mcp"]
    }
  }
}

如何找到您的数据库

Vetroscope 将其 SQLite 存储在：

  • macOS：~/Library/Application Support/Vetroscope/

  • Windows：%APPDATA%\Vetroscope\

  • Linux：~/.config/Vetroscope/

如果您已登录 Vetroscope 账户，活动数据库为 vetroscope-<userId>.db（记录在 auth-state.json 中）。否则为匿名 vetroscope.db。

您可以使用环境变量覆盖任一设置：

环境变量

用途

VETROSCOPE_DIR

覆盖应用数据目录

VETROSCOPE_DB_PATH

指向显式的 .db 文件

示例提示

  • “我这周在 After Effects 上花了多少时间？”

  • “我昨天做了什么？”

  • “我今天能按计划完成编码目标吗？”

  • “我这个月接触最多的前三个项目是什么？”

  • “显示本周所有涉及‘Vetroscope’项目的会话。”

  • “我这个月在 Vetroscope Dev 标签上花了多少时间？”

  • “我通常在一天中的什么时间使用 Cursor？”

  • “上周工作日工作时间（9–5）我做了多少小时的专注工作？”

  • “我昨天看了哪些 YouTube 视频，看了多久？”

  • “我现在在做什么？”

  • “显示我今天最长的专注工作会话。”

  • “我连续多少天达成了编码目标？”

  • “周三我的‘眼科预约’标记期间发生了什么？”

  • “我是否曾经参与过一个叫‘Atlas’的项目？”

  • “我今年最忙的一天是哪天？”

  • “我这个月在 Mac 和 Windows 上分别花了多少编码时间？”

  • “这周我工作时有音乐播放的时间占多少？”

  • “我今天只开着音乐听歌花了多长时间？”

  • “我这个月做了多少创意工作，多少编码工作？”

  • “我本周排名前五的艺术家是谁？”

  • “我通常在一周中的什么时间用 Cursor 编码？”

本地开发

git clone https://github.com/rankin-works/Vetroscope-MCP.git
cd Vetroscope-MCP
npm install
npm run build
node dist/index.js   # starts a stdio MCP server (mainly useful via a client)

仅类型检查：

npm run typecheck

工作原理

该服务器是一个轻量查询适配器，基于 Vetroscope 写入的同一个 SQLite 数据库。它复现了 electron/database.ts 中使用的按桶去重的时长计算逻辑，因此总计与桌面仪表盘完全一致。

由于它直接读取模式，Vetroscope 的模式迁移可能会导致 MCP 失效。工具集刻意保持精简——是专门构建的，而不是通用的 SQL 接口——因此变更局限于 src/queries.ts。

稳定性保证

从 1.0.0 开始，vetroscope-mcp 遵循语义化版本。公共 API 接口——工具名称、参数名称、参数语义和响应字段名称——是稳定的，变更遵循以下规则：

变更

SemVer 版本提升

添加新工具

次要版本 (1.x.0)

为现有工具添加新的可选参数

次要版本

为现有响应添加新字段

次要版本

重命名工具、参数或响应字段

主版本 (2.0.0)

更改参数的可接受值或默认值

主版本

更改现有字段的含义（例如 秒 → 分钟）

主版本

移除工具、参数或响应字段

主版本

以破坏先前有效输入的方式加强验证

主版本

不改变 API 接口的错误修复和内部重构属于补丁版本（1.0.x）。

明确不在 SemVer 契约范围内的事项：

  • 未从 npm 包导出的内部辅助函数和类型

  • src/categories.ts 中的活动类别分类法（ID 保持稳定；Vetroscope 中的种子映射可能会随着时间对更多应用进行分类）

  • 工具描述的确切措辞

  • 错误消息文本

如果你基于 vetroscope-mcp 构建内容，并希望锁定到主版本，请在依赖中固定为 ^1.0.0。

查看 CHANGELOG.md 获取完整的发布历史。

许可证

MIT © Jacob Rankin

Install Server
A
license - permissive license
A
quality
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
1dRelease cycle
4Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • SQLite MCP Server

    santos-404
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server implementation that enables AI assistants to execute SQL queries and interact with SQLite databases through a structured interface.
    7
    MIT

  • SQLite MCP Server

    bhargava2019
    A
    license
    Not graded
    quality
    D
    maintenance
    Implements a Model Context Protocol server that enables natural language interactions with SQLite databases, providing tools to list tables, retrieve schemas, count rows, and execute read-only SQL queries.
    MIT

  • Productive Simple MCP

    druellan
    A
    license
    A
    quality
    A
    maintenance
    A Model Context Protocol (MCP) server for accessing Productive.io API endpoints (projects, tasks, comments, todos), tailored for read-only operations, providing streamlined access to essential data while minimizing token consumption
    18
    MIT

View all related MCP servers

Related MCP Connectors

  • hithereiamaliff-mcp-nextcloud

    A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…

  • mcp

    A Model Context Protocol server for Wix AI tools

  • classquill-mcp

    Read-only MCP server for ClassQuill, a tutoring-business-management platform.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rankin-works/Vetroscope-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server