Skip to main content
Glama

Time Tracking MCP

by markwharton
GitHub
TypeScript
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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
-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

Enables natural language time tracking through Claude with markdown file storage. Supports multi-company tracking, flexible time parsing, auto-calculated summaries, and commitment warnings all through conversational input.

  1. Features
    1. Quick Start
      1. 1. Install
      2. 2. Configure Claude Desktop
      3. 3. Set Up Your Time Tracking Directory
      4. 4. Restart Claude Desktop
    2. Usage
      1. Natural Language Examples
        1. File Structure
          1. Tools Available
            1. Configuration
              1. Environment Variables
              2. Company Config (config.json)
            2. Development
              1. Versioning
                1. Architecture
                  1. Why MCP?
                    1. License
                      1. Author

                        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