MCP Toggl Server

Instructions

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 };
  });