Todoist MCP Server

Instructions

Implementation Reference

• src/tools/task-queries.ts:246-258 (handler)

  The handler function for the 'search_tasks_using_or' tool. It takes search_terms, calls the core searchTasksUsingOr function, and returns formatted JSON response.

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

• src/tools/task-queries.ts:227-245 (schema)

  The schema definition for the 'search_tasks_using_or' tool, specifying name, description, and input schema requiring search_terms array.

  schema: {
    name: 'search_tasks_using_or',
    description:
      'Search for tasks in Todoist using OR logic - any search term can match. Search query examples: meeting (basic text search), *report* (wildcard search), "buy groceries" (quoted, exact phrase search). Returns structured JSON data with task details including id, content, description, completion status, labels, priority, due date, and comment count.',
    inputSchema: {
      type: 'object',
      properties: {
        search_terms: {
          type: 'array',
          items: {
            type: 'string',
          },
          description:
            'Array of search terms. Any term can be present in matching tasks. Examples: ["meeting", "team"], ["weekly", "report", "friday"]',
        },
      },
      required: ['search_terms'],
    },
  },

• src/services/tasks/task-search.ts:104-153 (helper)

  Core helper function implementing the OR search logic using Todoist API filter with 'search:term1 | search:term2' syntax, processes tasks, caches names, returns structured TasksResponse.

  export async function searchTasksUsingOr(
    searchTerms: string[]
  ): Promise<TasksResponse> {
    if (searchTerms.length === 0) {
      throw new Error('At least one search term is required');
    }
  
    // Validate that all search terms are non-empty after trimming
    const trimmedTerms = searchTerms.map((term) => term.trim());
    if (trimmedTerms.some((term) => term === '')) {
      throw new Error('All search terms must be non-empty');
    }
  
    const todoistClient = getTodoistClient();
  
    try {
      // Build the filter string by joining terms with " | " operator
      const filterString = trimmedTerms
        .map((term) => `search:${term}`)
        .join(' | ');
  
      const response = await todoistClient.get<TodoistTask[]>(
        `/tasks?filter=${encodeURIComponent(filterString)}`
      );
  
      const tasks = response.data.map((task) => ({
        id: parseInt(task.id),
        content: task.content,
        description: task.description,
        is_completed: task.is_completed,
        labels: task.labels,
        priority: task.priority,
        due_date: task.due?.date || null,
        url: task.url,
        comment_count: task.comment_count,
      }));
  
      // Store task names in cache
      tasks.forEach((task) => {
        setTaskName(task.id.toString(), task.content);
      });
  
      return {
        tasks,
        total_count: tasks.length,
      };
    } catch (error) {
      throw new Error(`Failed to or search tasks: ${getErrorMessage(error)}`);
    }
  }

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

  Registration of the tool handler in the toolsWithArgs dispatch map 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:31-102 (registration)

  Import of the tool for use in the MCP server.

    searchTasksUsingOrTool,
    getChoresDueTodayTool,
    getTasksDueTomorrowTool,
    getTasksDueThisWeekTool,
    getTicklerTasksTool,
    listGtdProjectsTool,
    getWaitingTasksTool,
    getRecentMediaTool,
    getAreasOfFocusTool,
    getShoppingListTool,
    completeBeckyTaskTool,
    listBrianTimeSensitiveTasksTool,
    listBeckyTimeSensitiveTasksTool,
  } from './tools';
  import { handleToolRequest } from './handlers/tool-request-handler';
  import { join } from 'path';
  import { dirname } from 'path';
  import { fileURLToPath } from 'url';
  
  const __filename = fileURLToPath(import.meta.url);
  const __dirname = dirname(__filename);
  const envPath = join(__dirname, '..', '.env');
  
  console.error('Loading .env file from:', envPath);
  config({ path: envPath });
  
  // Validate required environment variables
  const requiredEnvVars = ['TODOIST_API_TOKEN'];
  const missingVars = requiredEnvVars.filter((varName) => !process.env[varName]);
  
  if (missingVars.length > 0) {
    console.error(
      'Missing required environment variables:',
      missingVars.join(', ')
    );
    console.error('Please create a .env file with the required variables.');
    process.exit(1);
  }
  
  const server = new Server({
    name: 'todoist-mcp',
    version: '1.0.0',
    capabilities: {
      tools: {},
    },
  });
  
  // List tools
  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        getTaskCommentsTool.schema,
        listPersonalInboxTasksTool.schema,
        listBrianInboxPerBeckyTasksTool.schema,
        listBeckyInboxPerBrianTasksTool.schema,
        listNextActionsTool.schema,
        getBrianOnlyProjectsTool.schema,
        getBrianSharedProjectsTool.schema,
        getBeckySharedProjectsTool.schema,
        getInboxProjectsTool.schema,
        createProjectLabelTool.schema,
        createTaskCommentTool.schema,
        updateTaskTool.schema,
        createTaskTool.schema,
        moveTaskTool.schema,
        getContextLabelsTool.schema,
        getTasksWithLabelTool.schema,
        completeTaskTool.schema,
        uncompleteTaskTool.schema,
        searchTasksTool.schema,
        searchTasksUsingAndTool.schema,
        searchTasksUsingOrTool.schema,