toggl_start_timer
Start a new time entry timer in Toggl Track to track work hours with description, project, task, and tags for accurate time management.
Instructions
Start a new time entry timer
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| description | No | Description of the time entry | |
| workspace_id | No | Workspace ID (uses default if not provided) | |
| project_id | No | Project ID (optional) | |
| task_id | No | Task ID (optional) | |
| tags | No | Tags for the entry |
Implementation Reference
- src/index.ts:491-518 (handler)MCP server handler for 'toggl_start_timer' tool call: extracts parameters, calls TogglAPI.startTimer, hydrates the entry with cache, and returns formatted success response.
case 'toggl_start_timer': { const workspaceId = args?.workspace_id || defaultWorkspaceId; if (!workspaceId) { throw new Error('Workspace ID required (set TOGGL_DEFAULT_WORKSPACE_ID or provide workspace_id)'); } const entry = await api.startTimer( workspaceId as number, args?.description as string | undefined, args?.project_id as number | undefined, args?.task_id as number | undefined, args?.tags as string[] | undefined ); await ensureCache(); const hydrated = await cache.hydrateTimeEntries([entry]); return { content: [{ type: 'text', text: JSON.stringify({ success: true, message: 'Timer started', entry: hydrated[0] }, null, 2) }] }; } - src/index.ts:188-217 (schema)Tool schema definition for 'toggl_start_timer' including name, description, and input schema for parameters.
{ name: 'toggl_start_timer', description: 'Start a new time entry timer', inputSchema: { type: 'object', properties: { description: { type: 'string', description: 'Description of the time entry' }, workspace_id: { type: 'number', description: 'Workspace ID (uses default if not provided)' }, project_id: { type: 'number', description: 'Project ID (optional)' }, task_id: { type: 'number', description: 'Task ID (optional)' }, tags: { type: 'array', items: { type: 'string' }, description: 'Tags for the entry' } } }, }, - src/toggl-api.ts:208-219 (helper)TogglAPI.startTimer method: constructs the time entry payload with running timer (duration -1) and delegates to createTimeEntry.
async startTimer(workspaceId: number, description?: string, projectId?: number, taskId?: number, tags?: string[]): Promise<TimeEntry> { const entry: Partial<CreateTimeEntryRequest> = { description, project_id: projectId, task_id: taskId, tags, start: new Date().toISOString(), duration: -1 // Negative duration indicates running timer }; return this.createTimeEntry(workspaceId, entry); } - src/toggl-api.ts:189-198 (helper)Core API call helper: formats and POSTs the time entry creation request to Toggl API.
async createTimeEntry(workspaceId: number, entry: Partial<CreateTimeEntryRequest>): Promise<TimeEntry> { const payload: CreateTimeEntryRequest = { workspace_id: workspaceId, created_with: 'mcp-toggl', start: entry.start || new Date().toISOString(), ...entry }; return this.request<TimeEntry>('POST', `/workspaces/${workspaceId}/time_entries`, payload); } - src/index.ts:386-388 (registration)Registers all tools including 'toggl_start_timer' by returning the tools array in response to ListToolsRequest.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools }; });