Todoist MCP Server

Instructions

Implementation Reference

• src/tools/comments.ts:121-134 (handler)

  The handler function for the 'get_context_labels' tool. It executes the tool logic by calling getContextLabels() from the service and returns the result as MCP-formatted content.

    handler: async () => {
      console.error('Executing get_context_labels...');
      const result = await getContextLabels();
      console.error('get_context_labels completed successfully');
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    },
  };

• src/services/labels/labels.ts:116-138 (helper)

  Core helper function that fetches all Todoist labels, filters those starting with 'context:', and returns structured LabelsResponse.

  export async function getContextLabels(): Promise<LabelsResponse> {
    const todoistClient = getTodoistClient();
  
    try {
      const response = await todoistClient.get<TodoistLabel[]>('/labels');
      const contextLabels = response.data
        .filter((label) => label.name.startsWith('context:'))
        .map((label) => ({
          id: parseInt(label.id),
          name: label.name,
          color: label.color,
          order: label.order,
          is_favorite: label.is_favorite,
        }));
  
      return {
        labels: contextLabels,
        total_count: contextLabels.length,
      };
    } catch (error) {
      throw new Error(`Failed to get context labels: ${getErrorMessage(error)}`);
    }
  }

• src/tools/comments.ts:111-120 (schema)

  Schema definition for the 'get_context_labels' tool, specifying name, description, and empty input schema (no parameters required).

  schema: {
    name: 'get_context_labels',
    description:
      'Get all context labels from Todoist. Context labels are labels that start with "context:" and are used to organize tasks by context (e.g., context:home, context:office, context:mobile).',
    inputSchema: {
      type: 'object',
      properties: {},
      required: [],
    },
  },

• src/handlers/tool-request-handler.ts:66-87 (registration)

  Registration of the get_context_labels tool handler in the toolsWithoutArgs registry used by handleToolRequest to dispatch tool calls.

  const toolsWithoutArgs: Record<string, () => Promise<ToolResponse>> = {
    list_personal_inbox_tasks: listPersonalInboxTasksTool.handler,
    list_brian_inbox_per_becky_tasks: listBrianInboxPerBeckyTasksTool.handler,
    list_becky_inbox_per_brian_tasks: listBeckyInboxPerBrianTasksTool.handler,
    list_next_actions: listNextActionsTool.handler,
    get_brian_only_projects: getBrianOnlyProjectsTool.handler,
    get_brian_shared_projects: getBrianSharedProjectsTool.handler,
    get_becky_shared_projects: getBeckySharedProjectsTool.handler,
    get_inbox_projects: getInboxProjectsTool.handler,
    get_context_labels: getContextLabelsTool.handler,
    get_chores_due_today: getChoresDueTodayTool.handler,
    get_tasks_due_tomorrow: getTasksDueTomorrowTool.handler,
    get_tasks_due_this_week: getTasksDueThisWeekTool.handler,
    get_tickler_tasks: getTicklerTasksTool.handler,
    list_gtd_projects: listGtdProjectsTool.handler,
    get_waiting_tasks: getWaitingTasksTool.handler,
    get_recent_media: getRecentMediaTool.handler,
    get_areas_of_focus: getAreasOfFocusTool.handler,
    get_shopping_list: getShoppingListTool.handler,
    list_brian_time_sensitive_tasks: listBrianTimeSensitiveTasksTool.handler,
    list_becky_time_sensitive_tasks: listBeckyTimeSensitiveTasksTool.handler,
  };

• src/index.ts:96-96 (registration)

  Registration of the tool schema in the MCP server's listTools response.

  getContextLabelsTool.schema,