timesheet-data

Timesheet Data MCP

MCP server that provides work checkpoint querying and timesheet report storage for AI assistants. Part of a personal AI-powered time tracking system — reads checkpoints logged via the Work Checkpoints Raycast extension and stores finalized timesheet reports in a local SQLite database.

How it fits together

┌─────────────────────┐
│  Raycast Extension  │  ← work-checkpoints
│  (logs checkpoints) │
└────────┬────────────┘
         │ writes
         ▼
   checkpoints.json     ← flat file, local only
         │
         │ reads
         ▼
┌─────────────────────┐
│   MCP Server        │  ← this repo
│   (this repo)       │
└────────┬────────────┘
         │ exposes tools to
         ▼
   Claude Desktop       ← generates timesheet from checkpoints
         │
         │ saves finalized reports
         ▼
     timesheet.db       ← SQLite database

Tools

Checkpoint tools (read from JSON)

| Tool | Description | |---|---| | get_today_checkpoints | Returns all checkpoints for today | | get_checkpoints_by_date | Returns checkpoints for a given date | | get_all_checkpoints | Returns all checkpoints |

Timesheet tools (read/write SQLite)

| Tool | Description | |---|---| | save_final_report | Save a finalized report for a date (replaces any existing entries) | | update_report_entry | Update one or more fields of an existing entry by ID | | get_report_by_date | Get all entries for a specific date | | get_reports_by_range | Get all entries within a date range | | get_category_summary | Hours and percentage breakdown by category, with client work split | | get_weekly_summary | Category breakdown grouped by week (Mon–Fri) for trend charts |

Categories

Entries are classified as: client_project, client_maintenance, internal_dev, or non_billable.

Setup

npm install
npm run build

Add to your Claude Desktop config (claude_desktop_config.json): ``json { "mcpServers": { "timesheet-data": { "command": "node", "args": ["/path/to/timesheet-data-mcp/dist/index.js"], "env": { "CHECKPOINTS_PATH": "/path/to/checkpoints.json" } } } } ``

• CHECKPOINTS_PATH (required) — path to the checkpoints.json file synced by the Raycast extension
• TIMESHEET_DB_PATH (optional) — defaults to ~/Library/Application Support/timesheet-assistant/timesheet.db

The database and table are created automatically on first run.

Scripts

| Script | Description | |---|---| | npm run build | Compile TypeScript | | npm test | Run tests | | npm run lint | Check for lint and format issues | | npm run lint:fix | Auto-fix lint issues | | npm run format | Auto-format source files |

Related

• work-checkpoints — Raycast extension that logs the checkpoints