Skip to main content
Glama
rankin-works

Vetroscope MCP

by rankin-works
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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 broad categories: editor, browser, adobe, communication, gaming, productivity, creative, etc. Mirrors Vetroscope's internal app grouping.

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

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 set of canonical app names in src/categories.ts (the categorizeApp function may classify the same app differently between minor versions as Vetroscope adds apps)

  • 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

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (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

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