Time Tracking MCP

Natural language time tracking for Claude Desktop using Model Context Protocol (MCP).

Features

• 🗣️ Natural Language Input - Just say "2h on security review"

• 📝 Markdown Storage - Human-readable files you can edit anywhere

• 🏢 Multi-Company Support - Track time across multiple clients/companies

• ⏰ Flexible Time Parsing - "2h", "90 minutes", "yesterday afternoon"

• 📊 Auto-calculated Summaries - Weekly totals and commitment tracking

• 🏷️ Smart Tagging - Auto-categorize by #development, #meeting, #admin

• ⚠️ Commitment Warnings - Stay within your hour limits

Quick Start

1. Install

git clone <repo-url> time-tracking-mcp
cd time-tracking-mcp
npm install
npm run build

2. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "TimeTracking": {
      "command": "/path/to/node",
      "args": ["/path/to/time-tracking-mcp/dist/server.js"],
      "env": {
        "TIME_TRACKING_DIR": "/Users/you/Documents/time-tracking",
        "COMPANIES": "helimods,clientx",
        "DEFAULT_COMPANY": "helimods",
        "DISPLAY_TIMEZONE_OFFSET": "10",
        "DISPLAY_TIMEZONE_STRING": "AEST"
      }
    }
  }
}

3. Set Up Your Time Tracking Directory

mkdir -p ~/Documents/time-tracking/helimods
mkdir -p ~/Documents/time-tracking/clientx

Create ~/Documents/time-tracking/helimods/config.json:

{
  "company": "HeliMods",
  "commitments": {
    "development": { "limit": 20, "unit": "hours/week" },
    "meeting": { "limit": 5, "unit": "hours/week" },
    "total": { "limit": 25, "unit": "hours/week" }
  },
  "projects": {
    "Conduit MCP": {
      "tags": ["development", "security"],
      "commitment": "development"
    }
  }
}

4. Restart Claude Desktop

Close and reopen Claude Desktop to load the new MCP server.

Usage

Just talk naturally to Claude:

You: "Just spent 2 hours on Conduit security review"
Claude: "Logged! Added 2h for Conduit security review at 17:45. 
        You're at 23.5h this week (94% of 25h limit)."

You: "How am I tracking this week?"
Claude: "Week 42 Summary:
        • Total: 23.5h / 25h (94%)
        • Development: 18.0h / 20h (90%)  
        • Meetings: 5.5h / 5h ⚠️ (110%)"

You: "Client meeting yesterday 90 minutes"
Claude: "Logged 1.5h for client meeting on Oct 16 at 15:00 ✓"

Natural Language Examples

Quick logging:

• "2h on security review"

• "Just finished 90 minutes on client meeting"

• "Spent half an hour on email"

Retroactive entries:

• "Yesterday afternoon I did 3 hours of code review"

• "This morning 2h on planning"

• "2 hours ago started working on that bug fix"

Checking status:

• "How many hours this week?"

• "Am I over my limit?"

• "What did I work on today?"

• "Show me this week's report"

Multi-company:

• "2h on project X for clientx"

• "Meeting 1h for helimods"

File Structure

~/Documents/time-tracking/
  helimods/
    config.json
    2025-week-42.md
    2025-week-43.md
  clientx/
    config.json
    2025-week-42.md

Each markdown file is human-readable and editable:

# Time Tracking - HeliMods - Week 42 (Oct 14-20, 2025)

## Summary
- **Total:** 23.5h / 25h limit (94%)
- **Development:** 18.0h / 20h (90%)
- **Meetings:** 5.5h / 5h ⚠️ OVER by 0.5h

---

## 2025-10-17 Thursday (6.5h)

- 17:45 Client standup (1.75h) #meeting
- 14:00 Time tracking design (1.5h) #development #meta
- 10:00 Security review (2.5h) #development #security
- 09:15 Email and admin (0.75h) #admin

Tools Available

Claude automatically uses these tools when you interact naturally:

• log_time - Log a completed task

• check_hours - Check time totals

• weekly_report - Generate formatted report

• status - Quick status check

You never call these directly - just talk to Claude naturally!

Configuration

Environment Variables

• TIME_TRACKING_DIR - Where to store markdown files (default: ~/Documents/time-tracking)

• COMPANIES - Comma-separated list of companies (default: default)

• DEFAULT_COMPANY - Default company when not specified (default: first company)

• DISPLAY_TIMEZONE_OFFSET - Hours offset from UTC (default: 0)

• DISPLAY_TIMEZONE_STRING - Timezone display name (default: UTC)

Company Config (config.json)

Each company directory should have a config.json:

{
  "company": "Company Name",
  "commitments": {
    "development": { "limit": 20, "unit": "hours/week" },
    "meeting": { "limit": 5, "unit": "hours/week" },
    "total": { "limit": 25, "unit": "hours/week" }
  },
  "projects": {
    "Project Name": {
      "tags": ["development", "security"],
      "commitment": "development"
    }
  },
  "tagMappings": {
    "dev": "development",
    "sync": "meeting"
  }
}

Development

# Build
npm run build

# Development mode (auto-reload)
npm run dev

# Clean build
npm run rebuild

# Release (semantic versioning)
npm run release        # Auto-increment patch
npm run release:minor  # Increment minor version
npm run release:major  # Increment major version

Versioning

This project uses commit-and-tag-version for semantic versioning.

Commit message format:

feat: add support for monthly reports
fix: correct duration parsing for fractional hours
perf: optimize summary calculations

Architecture

• MCP Server - Provides tools to Claude

• Natural Language - Claude parses your intent

• Markdown Storage - Simple, portable, human-editable

• Auto-summaries - Calculated on-the-fly from entries

Why MCP?

Traditional time tracking tools require context switching and structured input. With MCP:

1. Stay in Claude - no app switching

2. Natural language - no forms or timers

3. Voice-friendly - Mac dictation works perfectly

4. Portable data - plain markdown files

5. AI-enhanced - Claude understands your intent

License

MIT

Author

Mark Wharton