TrackingTime MCP Server

An MCP (Model Context Protocol) server that connects AI assistants like Claude to the TrackingTime API v4. Manage projects, tasks, time tracking, staff assignments, and customers through natural language.

Quick Start

1. Get your TrackingTime credentials

• App Password: TrackingTime → Manage → User Settings → Apps & Integrations → create a new App Password
• Account ID: Visible in your TrackingTime URL when logged in, or in account settings

2. Add to your AI assistant

Claude Code:

claude mcp add trackingtime -e TT_APP_PASSWORD=your-app-password -e TT_ACCOUNT_ID=your-account-id -- npx trackingtime-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "trackingtime": {
      "command": "npx",
      "args": ["trackingtime-mcp"],
      "env": {
        "TT_APP_PASSWORD": "your-app-password",
        "TT_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Restart your assistant after adding.

Alternative: Install from source

If you prefer to clone and build locally:

git clone https://github.com/ficus33/trackingtime-mcp.git
cd trackingtime-mcp
npm install
npm run build
cp .env.example .env   # then edit .env with your credentials

Then point your assistant at the local build:

claude mcp add trackingtime -- node /path/to/trackingtime-mcp/dist/index.js

Tools

Projects

Tool	Description
tt_list_projects	List projects (filter: ACTIVE/ARCHIVED/ALL/FOLLOWING)
tt_list_project_ids	List only project IDs (lightweight, for batch operations)
tt_search_projects	Search projects and tasks by keyword
tt_create_project	Create a new project
tt_update_project	Edit project name, customer, or service
tt_update_project_preferences	Set favorite, default view, show closed tasks
tt_get_project	Get single project with detail flags
tt_get_project_times	Get accumulated time for multiple projects
tt_get_project_users	See which staff are on a project
tt_archive_project	Archive a project (reversible)
tt_reopen_project	Reopen an archived project
tt_delete_project	Permanently delete a project
tt_merge_projects	Merge one project into another

Tasks

Tool	Description
tt_list_tasks	List tasks (filter: ACTIVE/ARCHIVED/ALL/TRACKING)
tt_create_task	Create a task with assignees, due date, estimate
tt_update_task	Edit task or reassign staff
tt_get_task	Get single task details
tt_get_task_times	Get accumulated times for multiple tasks
tt_search_tasks	Search tasks by name within projects
tt_sort_tasks	Reorder tasks by sort index
tt_import_tasks	Bulk import tasks with preview mode
tt_close_task	Mark a task as complete
tt_reopen_task	Reopen a completed task
tt_delete_task	Delete a task

Time Tracking

Tool	Description
tt_start_timer	Start a timer on a task
tt_stop_timer	Stop a running timer

Time Entries

Tool	Description
tt_list_time_entries	List entries by user/project/customer/task + date range
tt_add_time_entry	Add a manual time entry (duration in seconds)
tt_get_time_entry	Get a single time entry
tt_update_time_entry	Edit a time entry
tt_delete_time_entry	Delete a time entry
tt_get_events_summary	Summary of hours per user per day
tt_export_time_entries	Export as CSV
tt_mark_billed	Flag entries as billed
tt_mark_not_billed	Unflag billed entries

Users & Staff

Tool	Description
tt_list_users	List all staff (find user IDs)
tt_get_user	Get single user details
tt_update_user	Update user profile
tt_get_user_tasks	List a user's tasks grouped by project
tt_get_user_tracking	See what a user is currently tracking
tt_get_user_trackables	All projects and tasks assigned to a user
tt_get_user_projects	List projects assigned to a user
tt_assign_user_projects	Assign staff to projects
tt_remove_user_projects	Remove staff from projects
tt_archive_user	Deactivate a user (admin only)
tt_reactivate_user	Reactivate an archived user
tt_invite_users	Invite people by email

Customers

Tool	Description
tt_list_customers	List customers (filter: ACTIVE/ARCHIVED/ALL)
tt_get_customer	Get single customer details
tt_create_customer	Create a new customer
tt_update_customer	Edit customer details
tt_delete_customer	Permanently delete a customer
tt_archive_customer	Archive a customer (reversible)
tt_reactivate_customer	Reactivate an archived customer

Reducing tool count

All 54 tools are active by default. If you find this adds too much context for your AI assistant, you can clone the repo, comment out tools you don't need in src/tools.ts with /* */, and run npm run build to create a slimmer build.

Testing

Use MCP Inspector to test tools interactively:

npx @modelcontextprotocol/inspector npx trackingtime-mcp

API Notes

A few TrackingTime API quirks to be aware of:

• duration and accumulated_time are in seconds
• estimated_time and worked_hours are in hours
• Time entries are called "events" in the API
• Starting a timer when one is already running returns error 502 — use stop_running_task=true to auto-stop the current timer
• Dates use YYYY-MM-DD, datetimes use yyyy-MM-dd HH:mm:ss

Auth

This server uses TrackingTime's App Password authentication. Your real password is never stored. The App Password is sent as HTTP Basic auth (API_TOKEN:<app_password>) over SSL.

If an App Password is compromised, revoke it in TrackingTime and create a new one — no need to change your account password.

License

MIT