Skip to main content
Glama
markwharton

Time Tracking MCP

by markwharton
OverviewSchemaRelated ServersScoreDiscussions
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

Available Tools

1 tool
log_timeA

Log a completed time entry. This tool records work you've done.

Natural language examples Claude should parse:

  • "2h on security review" → task: "security review", duration: "2h"

  • "Client meeting yesterday 90 minutes" → task: "Client meeting", duration: "90m", date: "yesterday"

  • "Just finished 1.5h on code review" → task: "code review", duration: "1.5h"

Claude should extract:

  • task: What was worked on

  • duration: How long (2h, 90m, 1.5h, etc.)

  • time: When (optional, defaults to now)

  • date: Which day (optional, defaults to today)

  • tags: Inferred or explicit tags

  • company: Which company (optional, uses default)

ParametersJSON Schema
NameRequiredDescriptionDefault
companyNoCompany to log time for (optional, uses default if omitted)
dateNoDate of work (e.g., "today", "yesterday", "2025-10-17", omit for today)
durationYesDuration (e.g., "2h", "90m", "1.5h")
tagsNoTags to categorize work (e.g., ["development", "security"])
taskYesTask description (e.g., "Conduit MCP: Security review")
timeNoTime when work was done (e.g., "14:30", "2 hours ago", omit for now)

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is a non-readOnly, non-destructive operation. The description adds valuable behavioral context by explaining how Claude should parse natural language inputs and extract parameters, which goes beyond what annotations provide. It doesn't mention rate limits or authentication needs, but adds practical usage context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core purpose statement. The natural language examples and extraction guidelines are useful but could be more concise. Each section adds value, though the parameter extraction list somewhat duplicates information already in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema but excellent schema coverage (100%) and comprehensive annotations, the description provides good contextual completeness. It explains the tool's purpose, shows practical usage examples, and clarifies parameter extraction from natural language. The main gap is the lack of information about what happens after logging (confirmation, error cases, etc.).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the input schema already documents all parameters thoroughly. The description adds some semantic context by showing natural language mappings to parameters (e.g., '2h on security review' → task, duration) and explaining defaults, but doesn't significantly enhance the schema's parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('log') and resource ('completed time entry'), explaining it records work done. It distinguishes this from potential alternatives by specifying it's for logging completed time entries, though no sibling tools exist for comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implied usage through natural language examples showing when to use this tool (e.g., '2h on security review'), but lacks explicit guidance on when not to use it or alternatives. Since there are no sibling tools, the absence of comparative guidance is less critical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.0
    • First observedlog_time
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool 'log_time' has a clear, distinct purpose of recording time entries, so agents cannot misselect between non-existent alternatives.

Naming Consistency5/5

The naming pattern cannot be inconsistent with only one tool. The tool name 'log_time' follows a clear verb_noun convention that would be appropriate if more tools were added, but with a single tool, consistency is inherently perfect.

Tool Count2/5

A single tool is insufficient for a time tracking domain that typically requires operations like listing, editing, deleting, or reporting on time entries. While the tool itself is well-described, the server's scope feels incomplete with only creation/logging functionality, lacking basic CRUD coverage.

Completeness2/5

The tool set is severely incomplete for time tracking. There is no way to retrieve, update, delete, or analyze logged time entries—only creation via 'log_time'. This creates dead ends for agents that need to review or modify existing data, significantly limiting practical utility.

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Latest Blog Posts

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