Todoist MCP Server

Instructions

Implementation Reference

• src/tools/task-operations.ts:12-122 (handler)

  Definition of the createTaskTool including schema and handler function that implements the core logic for the 'create_task' MCP tool.

  export const createTaskTool: Tool = {
    schema: {
      name: 'create_task',
      description:
        'Create a new Todoist task with title, description, project, labels, priority, and due date. Only title is required.',
      inputSchema: {
        type: 'object',
        properties: {
          title: {
            type: 'string',
            description: 'The title/content of the task (required)',
          },
          description: {
            type: 'string',
            description: 'Description for the task',
          },
          project_id: {
            type: 'string',
            description: 'The ID of the project to create the task in',
          },
          labels: {
            type: 'array',
            items: {
              type: 'string',
            },
            description: 'Array of label names to assign to the task',
          },
          priority: {
            type: 'number',
            description: 'Priority level (1-4, where 1 is highest priority)',
          },
          due_date: {
            type: 'string',
            description: 'Due date in YYYY-MM-DD format',
          },
        },
        required: ['title'],
      },
    },
    handler: async (args: {
      title: string;
      description?: string;
      project_id?: string;
      labels?: string[];
      priority?: number;
      due_date?: string;
    }): Promise<{
      content: Array<{
        type: 'text';
        text: string;
      }>;
    }> => {
      console.error('Executing create_task...');
      const { title, description, project_id, labels, priority, due_date } = args;
  
      if (!title) {
        throw new Error('title is required');
      }
  
      try {
        // Build service parameters with only provided fields
        const serviceParams: any = {
          title,
        };
  
        if (description !== undefined) {
          serviceParams.description = description;
        }
  
        if (project_id !== undefined) {
          serviceParams.projectId = project_id;
        }
  
        if (labels !== undefined) {
          serviceParams.labels = labels;
        }
  
        if (priority !== undefined) {
          serviceParams.priority = priority;
        }
  
        if (due_date !== undefined) {
          serviceParams.dueDate = due_date;
        }
  
        const result = await createTask(serviceParams);
        console.error('create_task completed successfully');
  
        return {
          content: [
            {
              type: 'text',
              text: result,
            },
          ],
        };
      } catch (error) {
        console.error('create_task error:', error);
        return {
          content: [
            {
              type: 'text',
              text: `Error: ${
                error instanceof Error ? error.message : 'Unknown error'
              }`,
            },
          ],
        };
      }
    },
  };

• src/handlers/tool-request-handler.ts:50-64 (registration)

  Registration of the create_task handler in the toolsWithArgs registry used by handleToolRequest.

  const toolsWithArgs: Record<string, (args: any) => Promise<ToolResponse>> = {
    get_task_comments: getTaskCommentsTool.handler,
    create_project_label: createProjectLabelTool.handler,
    create_task_comment: createTaskCommentTool.handler,
    update_task: updateTaskTool.handler,
    create_task: createTaskTool.handler,
    move_task: moveTaskTool.handler,
    get_tasks_with_label: getTasksWithLabelTool.handler,
    complete_task: completeTaskTool.handler,
    uncomplete_task: uncompleteTaskTool.handler,
    search_tasks: searchTasksTool.handler,
    search_tasks_using_and: searchTasksUsingAndTool.handler,
    search_tasks_using_or: searchTasksUsingOrTool.handler,
    complete_becky_task: completeBeckyTaskTool.handler,
  };

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

  Registration of createTaskTool.schema in the list of tools returned by ListToolsRequestHandler.

  createTaskTool.schema,

• src/services/tasks/task-update.ts:169-188 (helper)

  The underlying service function createTask that performs the actual Todoist API call to create the task.

  export async function createTask(params: CreateTaskParams): Promise<string> {
    const client = getTodoistClient();
  
    try {
      const createPayload = buildCreatePayload(params);
  
      if (!client.post) {
        throw new Error('POST method not available on client');
      }
  
      const response = await client.post<{ content: string }>(
        '/tasks',
        createPayload
      );
  
      return `Task created successfully: ${response.data.content}`;
    } catch (error) {
      throw new Error(`Failed to create task: ${getErrorMessage(error)}`);
    }
  }