Skip to main content
Glama

Time Tracking MCP

by markwharton
OverviewInspectNewSchemaRelated ServersScore
TypeScript
Local

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

Deploy Server
A
security – no known vulnerabilities
-
license - not tested
A
quality - confirmed to work

How are these scores calculated?

Related Resources

Tools

New MCP Servers

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/markwharton/time-tracking-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server