Skip to main content
Glama
Vetroscope MCP

Vetroscope MCP

by rankin-works

Vetroscope MCP

A read-only Model Context Protocol server for Vetroscope — gives LLMs (Claude Desktop, Claude Code, ChatGPT, Cursor, …) context on how you've been spending your time, what projects you've been in, and how you're tracking against your goals.

Reads your local Vetroscope SQLite directly, read-only. No cloud round-trip, no auth, works offline.

Tools

Reports & breakdowns

Tool

What it does

get_report

Aggregate report for a period — total active seconds, top apps, top projects with sub-projects nested (YouTube videos, SoundCloud songs, Netflix episodes).

get_app_breakdown

Per-project breakdown for a single app over a period, with sub-projects.

get_app_stats

Deep stats for one app: lifetime totals, days active, daily series, hour-of-day distribution, weekday distribution.

get_tag_breakdown

Time-spent report for a single tag — top apps, top projects, daily series, active/passive split. include_descendants rolls up a parent tag's subtree.

get_tag_stats

Deep stats for one tag (counterpart to get_app_stats): lifetime totals, days active, daily series, hour-of-day and weekday distributions, plus the tag's parent and its children with rolled-up totals. Pass include_descendants to roll a parent tag's whole subtree into the series.

get_calendar

Dense per-day series (heatmap data) for any period — defaults to a full year.

get_device_breakdown

Per-device totals when you run Vetroscope across multiple machines.

get_music_split

Music-vs-work analysis: work-with-music / music-only / heads-down-work / other, plus per-source (Spotify, SoundCloud, …) overlap totals. Classifier is overridable per call.

get_category_breakdown

Time rolled up into Vetroscope activity categories (coding, creative, productivity, communication, entertainment, music, gaming, browsing, system, other) — same taxonomy as Charts / Settings.

get_listening_history

Top tracks and top artists across native music apps and browser music sites, plus per-day listening minutes. Artists parsed from the "Artist — Title" sub_project convention.

get_media_links

Canonical deep-links Vetroscope captured for media you actually played — Spotify spotify:track:… URIs and YouTube youtube.com/watch?v=… URLs — joined with the matching time data. Requires Vetroscope ≥ 0.2.30 with capture_media_links enabled.

get_focus_heatmap

7×24 grid of active foreground seconds — when do you usually do specific kinds of work. Optional app / project / tag filter to narrow to a single activity; include_descendants rolls up a parent tag's subtree.

Reference / lookup

Tool

What it does

list_tags

Your tags with id, name, color, sticky flag, archived flag, and parentId/parentName for nested tags. Archived tags hidden by default (include_archived to show).

list_categories

Activity-category taxonomy (id, label, color) — coding, creative, productivity, and the rest.

list_projects

Every (app, project) pair ever tracked with all-time totals + first/last seen + optional substring search.

list_markers

Your timeline markers (timestamp, label, color, icon, optional region end).

list_notes

Your notes (title, markdown-ish body excerpt with bullets/bold/italic/@mentions, optional timestamp/region, pin, folder). Optional folder filter (UUID, name, or none).

list_note_folders

Nested note folders (uuid, name, parentUuid, path, color).

list_reminders

Configured one-time, recurring, interval, and tag-threshold reminders. Disabled reminders are hidden by default (include_disabled to include them).

list_reminder_events

Reminder notification history, filterable by period, unread status, or reminder UUID.

Activity / status

Tool

What it does

get_sessions

Continuous activity blocks (start/end/duration) — the natural grain for "what did I work on this morning".

get_current_status

Most recent entry — what app/project right now, how recently, tracking vs idle.

query_entries

Filtered list of raw 30s entries (app / project / tag / search / period / mode).

Goals

Tool

What it does

get_goals_progress

Current progress on configured app / overall / tag goals.

get_goal_achievements

Historical record of which goals you hit on which days — drives streak questions.

All time-aware tools accept these shared filters:

Argument

Purpose

period

today · yesterday · week · month · year · single date YYYY-MM-DD · inclusive range YYYY-MM-DD..YYYY-MM-DD

hour_start / hour_end

Inclusive / exclusive hour-of-day filter in local time (e.g. 9 and 17 = working hours)

weekdays

Array of weekday integers (0=Sun, 1=Mon, …, 6=Sat). Pass [1,2,3,4,5] for weekdays only.

device

current (the local machine), a device UUID from get_device_breakdown, or a platform name (darwin, win32, browser-extension). Omit for all devices.

Every total is split into active foreground time and passive away-listening time (e.g. background music while idle), matching the dashboard's distinction.

Related MCP server: SQLite MCP Server

Requirements

  • Vetroscope installed and run at least once.

  • Node.js 18+.

Install

npx vetroscope-mcp

That's it — no global install needed. The first run will fetch the package from npm.

Configure your client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop.

Claude Code

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

ChatGPT (Developer Mode)

In the Connectors section, add a new MCP server with command npx and args -y vetroscope-mcp.

Cursor

Add to ~/.cursor/mcp.json:

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

How it finds your database

Vetroscope stores its SQLite at:

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

  • Windows: %APPDATA%\Vetroscope\

  • Linux: ~/.config/Vetroscope/

If you're signed into a Vetroscope account, the active DB is vetroscope-<userId>.db (recorded in auth-state.json). Otherwise it's the anonymous vetroscope.db.

You can override either piece with environment variables:

Env var

Purpose

VETROSCOPE_DIR

Override the app-data directory

VETROSCOPE_DB_PATH

Point at an explicit .db file

Example prompts

  • "How much time did I spend in After Effects this week?"

  • "What did I work on yesterday?"

  • "Am I on track to hit my coding goal today?"

  • "What were the top three projects I touched this month?"

  • "Show me every session that touched the 'Vetroscope' project this week."

  • "How much time did I spend on the Vetroscope Dev tag this month?"

  • "When during the day do I usually use Cursor?"

  • "How many hours of focused work did I do during weekday working hours (9–5) last week?"

  • "Which YouTube videos did I watch yesterday and how long?"

  • "What am I doing right now?"

  • "Show me my longest focused work sessions today."

  • "How many days in a row have I hit my coding goal?"

  • "What was happening during my 'Eye appointment' marker on Wednesday?"

  • "Have I ever worked on a project called 'Atlas'?"

  • "What was my busiest day this year?"

  • "How much of my coding time was on my Mac vs Windows this month?"

  • "How much of my work this week had music playing?"

  • "How long did I spend just listening to music with nothing else open today?"

  • "How much creative work vs coding did I do this month?"

  • "Who were my top five artists this week?"

  • "When during the week do I usually code in Cursor?"

Local development

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)

Type-check only:

npm run typecheck

How it works

The server is a thin query adapter over the same SQLite database that Vetroscope writes. It mirrors the bucket-distinct duration math used in electron/database.ts so totals match the desktop dashboard exactly.

Because it reads the schema directly, a Vetroscope schema migration could break the MCP. The set of tools is intentionally narrow — purpose-built rather than a generic SQL surface — so changes localize to src/queries.ts.

Stability guarantees

Starting with 1.0.0, vetroscope-mcp follows Semantic Versioning. The public API surface — tool names, parameter names, parameter semantics, and response field names — is stable and changes follow these rules:

Change

SemVer bump

Adding a new tool

minor (1.x.0)

Adding a new optional argument to an existing tool

minor

Adding a new field to an existing response

minor

Renaming a tool, argument, or response field

major (2.0.0)

Changing a parameter's accepted values or default

major

Changing the meaning of an existing field (e.g. seconds → minutes)

major

Removing a tool, argument, or response field

major

Tightening validation in a way that breaks previously valid input

major

Bug fixes and internal refactors that don't change the API surface are patch bumps (1.0.x).

Things explicitly not under the SemVer contract:

  • Internal helpers and types not exported from the npm package

  • The activity-category taxonomy in src/categories.ts (ids stay stable; seed mappings in Vetroscope may classify more apps over time)

  • The exact wording of tool descriptions

  • Error message text

If you build something on top of vetroscope-mcp and want to lock to a major version, pin to ^1.0.0 in your dependency.

See CHANGELOG.md for the full release history.

License

MIT © Jacob Rankin

Available Tools

25 tools
get_app_breakdownGet per-app breakdownA

Per-project breakdown for a single app over a period, with sub-projects nested when present (e.g. individual YouTube videos under the YouTube project). Use this when the user asks 'what was I working on in After Effects this week?' or 'which YouTube videos did I watch today?' Supports the same hour-of-day / weekday filter as get_report.

Inputs: app (required), limit, device, period, +4 more.

get_app_statsGet app statisticsA

Deeper statistics for a single app: lifetime totals (days active, first/last seen, average per active day), period totals, top projects, daily series, hour-of-day distribution (24 buckets), and weekday distribution (7 buckets). Use this for usage-pattern questions like 'when do I usually use Cursor?' or 'how has my After Effects time trended this month?'

Inputs: app (required), device, period.

get_calendarGet daily totals (calendar / heatmap)A

Dense per-day series of active and passive seconds for a period. Default period is 'year' for the GitHub-contribution-grid heatmap; pass any other period for narrower windows. Days with zero activity are explicitly included so streak / longest-gap analysis is straightforward.

Inputs: device, period.

get_category_breakdownGet time by activity categoryA

Rolls up app totals into Vetroscope activity categories (coding, creative, productivity, communication, entertainment, music, gaming, browsing, system, other) — the same taxonomy as Charts and Settings. Prefer category labels from the result verbatim. Apps without a mapping land in 'other'.

Inputs: device, period, hour_end, weekdays, +1 more.

get_current_statusGet current tracking statusA

Most recent activity: what app / project / sub-project the tracker last logged, how many seconds ago, and whether the tracker appears to be live (state='tracking') or quiescent (state='idle'). Use this for 'what am I doing right now?' questions.

Inputs: no named parameters.

get_device_breakdownGet per-device time breakdownA

Time per device for users who run Vetroscope across multiple machines (or paired with the browser extension). Each device reports total active / passive seconds, days active, first/last seen, and most-frequent platform. The user's current device is flagged with isCurrent=true. Each device's totalSeconds is DISTINCT 30s buckets on that device — the same wall-clock slice can be credited to every device that logged it, so summing devices can exceed get_report.totalSeconds.

Inputs: period.

get_focus_heatmapGet focus heatmap (hour × weekday grid)A

Returns a dense 168-cell grid (7 weekdays × 24 hours) of active foreground seconds. Reveals when you usually do specific kinds of work — patterns the marginal hour-of-day and weekday distributions can't show. Optional app / project / tag filters narrow the heatmap to a single activity (e.g. 'when do I usually code in Cursor?'); the tag is matched by name (case-insensitive) or id, and include_descendants rolls up a parent tag's whole subtree. Cells array is in (weekday, hour) order so cells[w*24 + h] indexes directly. 0=Sunday in weekday.

Inputs: app, tag, device, period, +2 more.

get_goal_achievementsGet goal achievement historyA

Historical record of goals the user hit — one row per (goal, day). Each row carries a snapshot of the goal as it was when achieved (so renamed/deleted goals still report sensibly). Useful for streak questions ('how many days in a row…') or summaries ('which goals did I hit last week?').

Inputs: period.

get_goals_progressGet goals progressB

Current progress on the user's configured Vetroscope goals (per-app and overall). Defaults to today.

Inputs: period.

get_listening_historyGet listening historyA

Top tracks and top artists across native music apps and browser music sites for the period, plus per-day listening minutes. Tracks come from entries.sub_project (e.g. 'Fox Stevenson — Tryhard'); artists are parsed from the 'Artist — Title' convention. Same music classifier as get_music_split — override via music_apps / music_browser_projects to e.g. include YouTube as music for this query.

Inputs: device, period, hour_end, weekdays, +5 more.

get_music_splitGet music vs work splitA

Splits the period's tracked time into three buckets: 'work with music' (a music app/site was logging while a non-music app was foreground), 'music only' (just listening, no work foreground), and 'work without music' (heads-down silent work). Also returns per-source totals (Spotify, SoundCloud, etc.) with each source's working-vs-not-working overlap. Music classification defaults to native music apps (Spotify, Apple Music) plus common browser music sites (SoundCloud, YouTube Music, Bandcamp, Tidal, Pandora) — override via music_apps / music_browser_projects to e.g. include YouTube as music for a specific question. The same hour-of-day / weekday / device filters as get_report are honored.

Inputs: device, period, hour_end, weekdays, +3 more.

get_reportGet time reportA

Aggregate Vetroscope time report for a period: total active seconds, top apps, and top projects (with sub-projects nested when present — e.g. individual YouTube videos, SoundCloud songs, Netflix episodes). Apps include the user's custom display_name when set. Applies the same SQLite settings as the desktop dashboard — ignored apps, ignored projects/breakdown patterns, and days_filter — plus optional hour-of-day/weekday/device filters layered on top. totalSeconds is wall-clock (each 30s bucket counted once even if two apps or two devices overlap). Per-app seconds are per-app buckets, so summing apps can exceed totalSeconds on overlap days. Do not sum the app rows and expect them to equal the header.

Inputs: device, period, hour_end, top_apps, +4 more.

get_sessionsGet activity sessionsA

Continuous activity blocks reconstructed from the raw 30s entries — the natural grain for 'what did I work on this morning?'. Two consecutive entries are one session when they share the same (app, project, sub_project) and are within 90s of each other. Each session reports start/end/duration and tag/app metadata.

Inputs: app, tag, limit, device, +6 more.

get_tag_breakdownGet tag breakdownA

Time-spent report for a single tag over a period: top apps and projects under the tag, daily series, active/passive split. Identify the tag by name (case-insensitive) — call list_tags first if you don't already know what's available. For a parent tag, set include_descendants to roll up the whole tag subtree.

Inputs: tag (required), device, period, hour_end, +5 more.

get_tag_statsGet tag statisticsA

Deeper statistics for a single tag — the tag counterpart to get_app_stats. Lifetime totals (days active, first/last seen, average per active day), period totals, top apps under the tag, daily series, hour-of-day (24 buckets) and weekday (7 buckets) distributions, plus the tag's place in the hierarchy: its parent and its immediate children with rolled-up totals. By default the tag's own totals count directly-assigned time only (children are reported separately); for a parent tag, set include_descendants to roll the whole subtree into the lifetime/period/hourOfDay/etc. series — the right way to ask 'how did I spend time under this parent tag, by hour?'. Identify the tag by name (case-insensitive) or numeric id — call list_tags first if unsure.

Inputs: tag (required), device, period, include_descendants.

list_categoriesList activity categoriesA

Returns Vetroscope's activity-category taxonomy (coding, creative, productivity, communication, entertainment, music, gaming, browsing, system, other) with label and color. Same ids Charts / Settings use. Call before get_category_breakdown when you need the full list of labels.

Inputs: no named parameters.

list_markersList timeline markersA

User-placed markers on the Vetroscope timeline (timestamp, optional end_timestamp for regions, label, color, icon). Pass a period to scope to a window — markers whose region OVERLAPS the period are returned. Omit period to list every marker.

Inputs: period.

list_note_foldersList note foldersA

Nested note folders (uuid, name, parentUuid, path, color). Use with list_notes when organizing or filtering by folder. Returns [] on installs that predate note folders.

Inputs: no named parameters.

list_notesList notesA

User notes (title, markdown-ish body excerpt with bullets/bold/italic/@mentions, optional timestamp/region, optional linked event, pin + folder). Pass a period to scope timed notes whose region OVERLAPS the window — timeless notes are omitted from period filters. Optional folder filters to a folder UUID/exact name, or "none" for unfiled. Omit period to list every note. Returns [] on installs that predate the notes table.

Inputs: folder, period.

list_projectsList all projectsA

Every (app, project) pair ever recorded with all-time totals, days active, and first/last seen. Optional case-insensitive substring search against project name or app. Useful for 'have I ever worked on something called X?' or 'what's my biggest project all-time?'

Inputs: limit, search.

list_reminder_eventsList reminder eventsA

History of reminder notifications that fired, with optional time window, unread-only status, or originating reminder UUID filters. Soft-deleted events and notification icon data are omitted.

Inputs: limit, period, unread_only, reminder_uuid.

list_remindersList remindersA

Configured Vetroscope reminders, including one-time, recurring weekday, every-N interval, tag/app period milestones (optional project breakdown), continuous app-session presence (optional project), and daily goal progress/milestone reminders. Disabled reminders are omitted by default; enable include_disabled to audit them. Notification icon data is not returned.

Inputs: include_disabled.

list_tagsList tagsA

List the user's tags (id, name, color, sticky flag, archived flag, and parentId/parentName for nested tags). Archived tags are hidden by default — set include_archived to see them. Useful as a reference before calling get_tag_breakdown / get_tag_stats or filtering entries by tag.

Inputs: include_archived.

query_entriesQuery raw entriesA

Filtered list of raw tracking entries. Useful for digging into specific projects, tags, or finding what window titles appeared. When a period is set, respects the same dashboard exclusions stored in SQLite (ignored apps/projects/breakdown patterns, days_filter) plus optional hour/device filters so aggregates stay consistent with Charts; omit period to bypass those scope rules while still filtering by tag/app/search/etc. Defaults to active foreground entries only — pass mode='passive' or 'all' to include away-listening (background music while idle). Returns at most 5000 rows; default 200.

Inputs: app, tag, mode, limit, +7 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools target a clearly distinct data surface—entries, apps, tags, devices, sessions, reminders, markers, notes, goals, and media—so the set is largely unambiguous. The closest pairs are get_app_stats vs get_app_breakdown and get_tag_stats vs get_tag_breakdown, which are similar enough that an agent could occasionally pick the wrong one without carefully reading the descriptions.

    Naming Consistency4/5

    The naming is broadly consistent: snake_case, verb-first, with get_* used for analytics/state and list_* for enumerations. The main deviation is query_entries, which could reasonably be list_entries, but overall the pattern is predictable and readable.

    Tool Count3/5

    At 25 tools, this is a heavy surface, especially with many analytics tools that cover overlapping views of the same time-tracking data. The breadth is understandable given the wide feature set, but it sits at the upper edge of what feels comfortable for an agent to navigate efficiently.

    Completeness4/5

    The read-only analytics surface is strong: it covers raw entries, sessions, reports, per-app/tag/category/device breakdowns, goals, reminders, notes, markers, media links, and heatmaps. Minor gaps include no direct goal-definition lister and no standalone project-stats endpoint, but agents can work around these with list_projects, get_goals_progress, and get_app_breakdown.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
    • 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
    • A
      license
      A
      quality
      B
      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