MCP Toggl Server

Instructions

Implementation Reference

• src/index.ts:722-747 (handler)

  MCP tool handler for 'toggl_list_projects': extracts workspace_id from arguments (falling back to env default), calls TogglAPI.getProjects, formats response with project details (id, name, active, billable, color, client_id), and returns as JSON text content.

  case 'toggl_list_projects': {
    const workspaceId = args?.workspace_id || defaultWorkspaceId;
    if (!workspaceId) {
      throw new Error('Workspace ID required (set TOGGL_DEFAULT_WORKSPACE_ID or provide workspace_id)');
    }
    
    const projects = await api.getProjects(workspaceId as number);
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ 
          workspace_id: workspaceId,
          count: projects.length,
          projects: projects.map(p => ({
            id: p.id,
            name: p.name,
            active: p.active,
            billable: p.billable,
            color: p.color,
            client_id: p.client_id
          }))
        }, null, 2)
      }]
    };
  }

• src/index.ts:324-336 (schema)

  Tool schema definition: name, description, and input schema accepting optional workspace_id (number).

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

• src/toggl-api.ts:106-108 (helper)

  TogglAPI.getProjects: Makes authenticated GET request to Toggl API endpoint /workspaces/{workspaceId}/projects to fetch list of projects.

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