Time Tracking

Open Source — GitScrum MCP Server is open source under the MIT license. Available on npm and GitHub. Model Context Protocol server for GitScrum — Claude, GitHub Copilot, Cursor, and any MCP-compatible client full operational access to your project management stack.

The time tool provides 9 actions for real-time timer management, time entry logging, and productivity analytics. Whether you're tracking billable hours for client work, measuring team productivity, or generating time reports for invoicing, the time tracking tool gives your AI assistant full control over GitScrum's time tracking system.

The tool supports two primary workflows: real-time timers (start/stop while you work) and time logs (view recorded entries). For analytics, the tool provides five reporting actions that cover individual productivity, team performance, and detailed timeline breakdowns.

Actions Overview

Timer Workflow

The core timer workflow follows a simple sequence: check for active timers → start a new timer → work → stop the timer. The MCP server enforces that only one timer can run at a time per user.

Checking Active Timers

Before starting a new timer, the AI assistant should check if a timer is already running. The active action returns the current timer details if one exists, or { active: false } if no timer is running.

The company_slug parameter is auto-resolved if omitted — the server uses your first accessible workspace.

You:  "What timers are currently running?"
AI:   Calls time action=active → returns current timer details or "no active timer"

You:  "Am I tracking time on anything?"
AI:   Calls time action=active → reports whether a timer is running and on which task

Starting a Timer

The start action begins a timer on a specific task. You need the task's UUID, which the AI assistant can obtain from the task tool (using actions like my, today, filter, or by_code).

The MCP server returns the timer object with a timetrackingid that you need for the stop action. The AI assistant retains this ID in the conversation context for when you're ready to stop.

You:  "Start a timer on task GS-123"
AI:   Looks up task by code → calls time action=start with task_uuid
      → "Timer started on 'Fix login validation'"

You:  "Track time on the API migration task"
AI:   Finds the task → calls time action=start
      → "Timer started on 'API v3 migration'"

You:  "Start tracking time on my current task"
AI:   Checks task action=today → picks the most relevant task → starts timer

Stopping a Timer

The stop action ends the currently running timer. It requires the timetrackingid, which the AI assistant obtains from the active action response.

You:  "Stop my running timer"
AI:   Calls time action=active → gets time_tracking_id
      → calls time action=stop → "Timer stopped. 1h 23m recorded on 'Fix login validation'"

You:  "I'm done working for now"
AI:   Checks for active timer → stops it if running

Timer Workflow Example

Here's a complete timer session as a natural conversation:

You:  "What am I tracking time on?"
AI:   Calls time action=active → "No active timer"

You:  "Start a timer on the login fix task"
AI:   Finds task → calls time action=start → "Timer started on 'Fix login validation'"

[... you work for 2 hours ...]

You:  "Stop the timer"
AI:   Calls time action=active → gets ID → calls time action=stop
      → "Timer stopped. 2h 04m recorded"

Time Logs

The logs action returns recorded time entries for a specific project. Each entry includes the task, user, duration, date, and optional description. This is the audit trail of all time tracked within the project.

Parameters

You:  "Show time logs for the Backend project"
AI:   Calls time action=logs → returns list of time entries with task, user, and duration

You:  "How much time was logged on the Backend project this week?"
AI:   Calls time action=logs → AI sums entries from current week

You:  "Who logged the most time on the Mobile App project?"
AI:   Calls time action=logs → AI groups by user and sums durations

Analytics and Reports

The time tool provides five analytics actions that aggregate time data for different purposes. All share a common parameter structure.

Common Parameters

Available Periods

Analytics

The analytics action returns a summary of time tracking data — total hours, average daily hours, distribution by project, and trend data. This is the overview dashboard for time tracking.

You:  "Show my time tracking analytics for this month"
AI:   Calls time action=analytics with period="this-month"
      → returns total hours, daily averages, project breakdown

You:  "How much time did I track last week?"
AI:   Calls time action=analytics with period="last-7-days"
      → returns total hours and daily distribution

Team

The team action returns time tracking data aggregated by team member. This shows who is tracking time, how much each person tracked, and on which projects. Managers use this for workload assessment and capacity planning.

You:  "Show team time tracking for this week"
AI:   Calls time action=team with period="last-7-days"
      → returns per-member hours, project breakdown

You:  "Who tracked the most hours this month?"
AI:   Calls time action=team with period="this-month"
      → AI identifies the top contributor

Reports

The reports action generates detailed time reports suitable for billing and invoicing. It supports different report types and optional hourly rate calculations.

You:  "Generate a time report for the Backend project this month"
AI:   Calls time action=reports with project_slug, period="this-month"
      → returns detailed time report with task-level breakdown

You:  "Show me the billable hours for Acme Corp at $150/hour"
AI:   Calls time action=reports with hourly_rate=150
      → returns report with calculated costs

You:  "Create an invoice-ready time report for last month"
AI:   Calls time action=reports with period="last-month"
      → returns detailed report with dates, tasks, durations, and totals

Productivity

The productivity action measures time tracking patterns and efficiency metrics — focus time, context switching frequency, productive hours by time of day, and consistency scores. This helps individual contributors and managers understand work patterns.

You:  "Show my productivity metrics for this week"
AI:   Calls time action=productivity with period="last-7-days"
      → returns focus time, productive hours, consistency data

You:  "How productive was the team last month?"
AI:   Calls time action=productivity with period="last-month"
      → returns team-wide productivity trends

Timeline

The timeline action returns a chronological view of time entries — a day-by-day, hour-by-hour breakdown of what was tracked and when. This is useful for reviewing how time was spent across a day or week.

You:  "Show me my time timeline for today"
AI:   Calls time action=timeline with period="today"
      → returns chronological list of tracked time blocks

You:  "What did I work on yesterday?"
AI:   Calls time action=timeline with period="yesterday"
      → returns ordered time entries with task details

Billing and Invoicing Workflow

For teams tracking billable hours, the time tool integrates with GitScrum's invoicing capabilities. Here's a typical billing workflow:

1. Track time throughout the period

Team members use timers or manual entries to track time on client tasks.

You:  "Start a timer on the Acme Corp API integration task"
AI:   Starts timer → you work → you stop when done

2. Review time at period end

Check the accumulated time before generating invoices.

You:  "Show me all time tracked for the Backend project this month"
AI:   Calls time action=logs → returns detailed entry list

You:  "What's the total billable hours for this month?"
AI:   Calls time action=reports with period="this-month" → returns totals

3. Generate billing report

Create a report with hourly rates for invoicing.

You:  "Generate a billing report at $150/hour for last month"
AI:   Calls time action=reports with hourly_rate=150, period="last-month"
      → returns report with hours × rate calculations

4. Analyze team capacity

Review team utilization for future planning.

You:  "How is the team's time distributed across projects?"
AI:   Calls time action=team with period="this-month"
      → returns per-member, per-project breakdown

Task Integration

Time tracking is tightly coupled with tasks. Every timer and manual entry is linked to a specific task. This means your AI assistant can:

• Start timers from task context. When reviewing your task list, tell the AI assistant which task to track time on. It resolves the task UUID automatically.

• View time data from task details. When you get task details with task action=get, the response includes time tracking data — total time logged, active timers, and time entries.

• Correlate time with sprint progress. Combine sprint action=stats with time analytics to understand how much effort each sprint consumed.

You:  "How much time have we spent on Sprint 14?"
AI:   Gets sprint tasks → cross-references with time logs → reports total hours

You:  "Start tracking the next task on my list"
AI:   Calls task action=today → picks the highest-priority task → starts timer

Period-Based Analysis

All analytics actions support the period parameter for consistent time-window filtering. When omitted, most actions default to the current scope (all time or current period, depending on the endpoint).

For recurring reporting, you can establish a pattern with your AI assistant:

You:  "Every Monday, show me last week's time report"
AI:   Calls time action=reports with period="last-7-days" → weekly summary

You:  "End-of-month time review"
AI:   Calls time action=analytics + team + productivity with period="this-month"
      → comprehensive monthly analysis

Context Auto-Resolution

The time tool supports automatic context resolution for companyslug. If you don't specify a workspace, the MCP server uses your first accessible workspace. For projectslug, the server can auto-resolve from the conversation context if established earlier.

The start action only requires task_uuid — the server determines the workspace and project from the task itself. This means you can go from task browsing to time tracking in a single step without re-specifying any context.

Next Steps

• Tasks: Manage the tasks you track time against.
• Sprints: Plan sprints and correlate time with sprint progress.
• Projects: Configure projects and review team members.
• Quick Start: Set up the MCP server if you haven't already.