Vetroscope MCP
The Vetroscope MCP server provides LLMs with read-only, local, offline access to your Vetroscope time-tracking data, enabling AI assistants to answer questions about how you spend your time, what you work on, and how you track against your goals.
Reports & Breakdowns
get_report– Aggregate time report: total active seconds, top apps, and top projects (including nested sub-projects like YouTube videos)get_app_breakdown/get_app_stats– Per-project breakdown and deep stats (daily series, hour-of-day, weekday distributions) for a specific appget_tag_breakdown/get_tag_stats– Time-spent report and deep stats for a specific tag, including active/passive splits and subtree rollupsget_category_breakdown– Roll up app time into broad categories (editor, browser, gaming, productivity, etc.)get_music_split– Analyze music vs. work time: work-with-music, music-only, and heads-down-work bucketsget_listening_history– Top tracks and artists from music apps and browser music sites, plus per-day listening minutesget_media_links– Canonical deep-links (Spotify URIs, YouTube URLs) for media played, joined with time dataget_device_breakdown– Per-device time totals across multiple machines
Visual Overviews
get_calendar– Dense per-day activity series (heatmap data) for any period, defaulting to a full yearget_focus_heatmap– 7×24 hour/weekday grid showing when you do specific kinds of work
Activity & Status
get_sessions– Continuous activity blocks (start/end/duration) reconstructed from raw entriesget_current_status– Most recent tracked entry: active app/project and whether tracking is live or idlequery_entries– Raw 30-second tracking entries filtered by app, project, tag, search term, or time period
Goals
get_goals_progress– Current progress on configured app, overall, or tag goalsget_goal_achievements– Historical record of goals hit per day, enabling streak analysis
Reference & Lookup
list_tags– All tags with id, name, color, sticky/archived flags, and parent infolist_projects– Every (app, project) pair ever tracked with all-time totals, days active, and first/last seen; supports substring searchlist_markers– Timeline markers with timestamp, label, color, icon, and optional region end
Shared Filtering — All time-aware tools support filtering by period (today, week, date range), hour of day, weekdays, and device. Data is read directly from the local SQLite database — no cloud, no authentication required.
Enables querying Netflix watch history and episodes, providing insights into viewing behavior.
Allows querying SoundCloud listening time and tracks, offering analysis of audio content consumption.
Provides tools for querying listening history, top tracks, and media links from Spotify, enabling analysis of music listening patterns.
Allows retrieval of YouTube watch history, including video URLs and time spent, to analyze video consumption habits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Vetroscope MCP what am I working on right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Aggregate report for a period — total active seconds, top apps, top projects with sub-projects nested (YouTube videos, SoundCloud songs, Netflix episodes). |
| Per-project breakdown for a single app over a period, with sub-projects. |
| Deep stats for one app: lifetime totals, days active, daily series, hour-of-day distribution, weekday distribution. |
| Time-spent report for a single tag — top apps, top projects, daily series, active/passive split. |
| Deep stats for one tag (counterpart to |
| Dense per-day series (heatmap data) for any period — defaults to a full year. |
| Per-device totals when you run Vetroscope across multiple machines. |
| 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. |
| Time rolled up into Vetroscope activity categories ( |
| 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. |
| Canonical deep-links Vetroscope captured for media you actually played — Spotify |
| 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; |
Reference / lookup
Tool | What it does |
| Your tags with id, name, color, sticky flag, archived flag, and parentId/parentName for nested tags. Archived tags hidden by default ( |
| Activity-category taxonomy (id, label, color) — coding, creative, productivity, and the rest. |
| Every (app, project) pair ever tracked with all-time totals + first/last seen + optional substring search. |
| Your timeline markers (timestamp, label, color, icon, optional region end). |
| Your notes (title, markdown-ish body excerpt with bullets/bold/italic/@mentions, optional timestamp/region, pin, folder). Optional |
| Nested note folders ( |
| Configured one-time, recurring, interval, and tag-threshold reminders. Disabled reminders are hidden by default ( |
| Reminder notification history, filterable by period, unread status, or reminder UUID. |
Activity / status
Tool | What it does |
| Continuous activity blocks (start/end/duration) — the natural grain for "what did I work on this morning". |
| Most recent entry — what app/project right now, how recently, tracking vs idle. |
| Filtered list of raw 30s entries (app / project / tag / search / period / mode). |
Goals
Tool | What it does |
| Current progress on configured app / overall / tag goals. |
| Historical record of which goals you hit on which days — drives streak questions. |
All time-aware tools accept these shared filters:
Argument | Purpose |
|
|
| Inclusive / exclusive hour-of-day filter in local time (e.g. |
| Array of weekday integers (0=Sun, 1=Mon, …, 6=Sat). Pass |
|
|
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-mcpThat'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-mcpChatGPT (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 |
| Override the app-data directory |
| Point at an explicit |
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 typecheckHow 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 toolsget_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_media_linksGet captured media URLs (Spotify tracks, YouTube videos)A
Lists canonical deep-links Vetroscope captured for media the user actually played — Spotify spotify:track:… URIs and YouTube https://www.youtube.com/watch?v=… URLs. Each row carries the matching time data so you can answer 'what YouTube videos did I rewatch this week + give me the link to the top one?' or 'send me a Spotify URI for the song I played the most yesterday'. Each row also includes a webUrl HTTPS variant — https://open.spotify.com/track/<id> for Spotify (which hands off to the desktop app when installed), same as url for YouTube — so a clickable link survives any markdown / chat renderer that strips custom URI schemes. Requires Vetroscope ≥ 0.2.30 with the capture_media_links setting enabled — available: false is returned on older installs or when nothing has been captured. With period set, the same dashboard filter stack as get_report applies and totals match Charts; without period, time columns are lifetime totals. URLs are filtered strictly at capture time (YouTube /watch only; track URIs only — no ads, no shorts, no channel pages) so anything returned here is safe to open directly.
Inputs: kind, limit, device, period, +4 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
Scored across 25 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Model Context Protocol server for todo.vu task management and time tracking.
A Model Context Protocol server for Wix AI tools
Model Context Protocol server for Studex tools, notifications, and profile integrations
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI assistants to explore and interact with Cursor IDE's SQLite databases, providing access to project data, chat history, and composer information.26-
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server implementation that enables AI assistants to execute SQL queries and interact with SQLite databases through a structured interface.7MIT
- AlicenseNot gradedqualityDmaintenanceImplements 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
- AlicenseAqualityBmaintenanceA 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 consumption18MIT