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

Reference / lookup

Activity / status

Goals

All time-aware tools accept these shared filters:

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

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:

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:

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