todoist_reminders
Set and manage task reminders in Todoist using relative time, specific dates, or location-based triggers to help users stay on top of deadlines and commitments.
Instructions
Manage reminders for Todoist tasks. Supports three reminder types: relative (minutes before task due date), absolute (specific date and time), and location (geofenced area). Natural language due dates supported (e.g., "tomorrow at 10:00", "every day", "every 4th").
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform on reminders | |
| due | No | Due date object for absolute reminders (supports natural language) | |
| item_id | No | Task ID for which the reminder is set | |
| loc_lat | No | Latitude (location reminders only) | |
| loc_long | No | Longitude (location reminders only) | |
| loc_trigger | No | Trigger type for location reminders | |
| minute_offset | No | Minutes before task due date (relative reminders only, max 43200 = 30 days) | |
| name | No | Location name (location reminders only) | |
| notify_uid | No | User ID to notify (optional) | |
| radius | No | Radius in meters (location reminders only, max 5000) | |
| reminder_id | No | Reminder ID for get/update/delete operations | |
| type | No | Type of reminder: relative (minutes before due), absolute (specific datetime), location (geofenced) |
Implementation Reference
- src/tools/todoist-reminders.ts:327-378 (handler)Main handler function that validates input, dispatches to action-specific private methods (create, get, update, delete, list), adds metadata, and handles errors.async execute(params: unknown): Promise<TodoistRemindersOutput> { const startTime = Date.now(); try { // Validate API token before processing request await TokenValidatorSingleton.validateOnce(); // Validate input parameters const validatedParams = TodoistRemindersInputSchema.parse(params); // Validate action-specific required fields this.validateActionRequirements(validatedParams); let result: TodoistRemindersOutput; switch (validatedParams.action) { case 'create': result = await this.handleCreate(validatedParams); break; case 'get': result = await this.handleGet(validatedParams); break; case 'update': result = await this.handleUpdate(validatedParams); break; case 'delete': result = await this.handleDelete(validatedParams); break; case 'list': result = await this.handleList(validatedParams); break; default: throw new ValidationError('Invalid action specified'); } // Add operation time to metadata if (result.metadata) { result.metadata.operation_time = Date.now() - startTime; } else { result.metadata = { operation_time: Date.now() - startTime, }; } return result; } catch (error) { return handleToolError( error, Date.now() - startTime ) as TodoistRemindersOutput; } }
- src/tools/todoist-reminders.ts:16-43 (schema)Zod schema for input validation of the todoist_reminders tool parameters.const TodoistRemindersInputSchema = z.object({ action: z.enum(['create', 'get', 'update', 'delete', 'list']), // Reminder type (for create/update actions) type: z.enum(['relative', 'absolute', 'location']).optional(), // Item/Reminder IDs item_id: z.string().optional(), reminder_id: z.string().optional(), // Relative reminder fields minute_offset: z.number().int().optional(), // Absolute reminder fields due: z .object({ date: z.string().optional(), string: z.string().optional(), timezone: z.string().nullable().optional(), is_recurring: z.boolean().optional(), lang: z.string().optional(), }) .optional(), // Location reminder fields name: z.string().optional(), loc_lat: z.string().optional(), loc_long: z.string().optional(), loc_trigger: z.enum(['on_enter', 'on_leave']).optional(), radius: z.number().int().optional(), // Common fields notify_uid: z.string().optional(), });
- JSON schema definition for MCP tool input, used in tool definition.public readonly inputSchema = { type: 'object', properties: { action: { type: 'string', enum: ['create', 'get', 'update', 'delete', 'list'], description: 'Action to perform on reminders', }, type: { type: 'string', enum: ['relative', 'absolute', 'location'], description: 'Type of reminder: relative (minutes before due), absolute (specific datetime), location (geofenced)', }, item_id: { type: 'string', description: 'Task ID for which the reminder is set', }, reminder_id: { type: 'string', description: 'Reminder ID for get/update/delete operations', }, minute_offset: { type: 'number', description: 'Minutes before task due date (relative reminders only, max 43200 = 30 days)', }, due: { type: 'object', description: 'Due date object for absolute reminders (supports natural language)', properties: { date: { type: 'string', description: 'ISO 8601 datetime' }, string: { type: 'string', description: 'Natural language date (e.g., "tomorrow at 10:00", "every day at 9am")', }, timezone: { type: 'string', description: 'Timezone for due date' }, is_recurring: { type: 'boolean', description: 'Whether reminder repeats', }, lang: { type: 'string', description: 'Language for parsing (default: en)', }, }, }, name: { type: 'string', description: 'Location name (location reminders only)', }, loc_lat: { type: 'string', description: 'Latitude (location reminders only)', }, loc_long: { type: 'string', description: 'Longitude (location reminders only)', }, loc_trigger: { type: 'string', enum: ['on_enter', 'on_leave'], description: 'Trigger type for location reminders', }, radius: { type: 'number', description: 'Radius in meters (location reminders only, max 5000)', }, notify_uid: { type: 'string', description: 'User ID to notify (optional)', }, }, required: ['action'], };
- src/server/impl.ts:67-92 (registration)Instantiation of TodoistRemindersTool and registration in the tools Map by name 'todoist_reminders'.const remindersTool = new TodoistRemindersTool(this.config); const labelsTool = new TodoistLabelsTool(this.config); const bulkTasksTool = new TodoistBulkTasksTool(this.config); // Register tools in the map this.tools.set('todoist_tasks', tasksTools); this.tools.set('todoist_projects', projectsTool); this.tools.set('todoist_sections', sectionsTool); this.tools.set('todoist_comments', commentsTool); this.tools.set('todoist_filters', filtersTool); this.tools.set('todoist_reminders', remindersTool); this.tools.set('todoist_labels', labelsTool); this.tools.set('todoist_bulk_tasks', bulkTasksTool); logger.info('All tools initialized successfully', { toolCount: this.tools.size, tools: Array.from(this.tools.keys()), }); } catch (error) { logger.error('Failed to initialize tools', { error }); throw new McpError( ErrorCode.InternalError, `Failed to initialize tools: ${error instanceof Error ? error.message : 'Unknown error'}` ); } }
- src/server/impl.ts:108-108 (registration)Includes the tool definition (name, description, inputSchema) in the list tools response.TodoistRemindersTool.getToolDefinition(),