toggl_start_timer
Start a new Toggl timer to track time for specific tasks with optional project, tags, and workspace details 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 | |
| project_id | No | Project ID (optional) | |
| tags | No | Tags for the entry | |
| task_id | No | Task ID (optional) | |
| workspace_id | No | Workspace ID (uses default if not provided) |
Implementation Reference
- src/index.ts:491-518 (handler)MCP tool handler for 'toggl_start_timer': extracts input arguments, determines workspace ID, calls TogglAPI.startTimer, hydrates the entry with cache data, and returns a success response with the entry details.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)Schema definition for the 'toggl_start_timer' tool, including name, description, and input schema properties.{ 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/index.ts:386-388 (registration)Registers the tools list (including 'toggl_start_timer') to be returned on ListTools requests.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools }; });
- src/toggl-api.ts:208-219 (helper)TogglAPI.startTimer helper: constructs payload for a 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)TogglAPI.createTimeEntry helper: formats the POST request payload and sends it to Toggl API to create the time entry.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); }