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,