MCP Toggl Server

Instructions

Implementation Reference

• src/index.ts:749-771 (handler)

  The primary handler for the 'toggl_list_clients' tool. It resolves the workspace ID, fetches clients using the TogglAPI, and returns a formatted JSON response containing workspace_id, count, and client details (id, name, archived).

  case 'toggl_list_clients': {
    const workspaceId = args?.workspace_id || defaultWorkspaceId;
    if (!workspaceId) {
      throw new Error('Workspace ID required (set TOGGL_DEFAULT_WORKSPACE_ID or provide workspace_id)');
    }
    
    const clients = await api.getClients(workspaceId as number);
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ 
          workspace_id: workspaceId,
          count: clients.length,
          clients: clients.map(c => ({
            id: c.id,
            name: c.name,
            archived: c.archived
          }))
        }, null, 2)
      }]
    };
  }

• src/index.ts:337-349 (schema)

  Tool schema definition for 'toggl_list_clients', including name, description, and input schema specifying an optional workspace_id parameter.

  {
    name: 'toggl_list_clients',
    description: 'List clients for a workspace',
    inputSchema: {
      type: 'object',
      properties: {
        workspace_id: {
          type: 'number',
          description: 'Workspace ID (uses default if not provided)'
        }
      }
    },
  },

• src/index.ts:386-388 (registration)

  Registration of all tools (including toggl_list_clients) via the ListToolsRequestSchema handler, which returns the complete tools array.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools };
  });

• src/toggl-api.ts:123-125 (helper)

  Helper method in TogglAPI class that makes the HTTP request to retrieve clients for a specific workspace from the Toggl Track API.

  async getClients(workspaceId: number): Promise<Client[]> {
    return this.request<Client[]>('GET', `/workspaces/${workspaceId}/clients`);
  }