todoist-mcp 1.0.0

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+  <h1></h1>
+  <img src="https://static-00.iconduck.com/assets.00/todoist-icon-512x512-v3a6dxo9.png" width="120"/>
+  <h1>Todoist MCP Server</h1>
+  <p>A Model Context Protocol (MCP) server implementation that integrates Claude and other AI assistants with Todoist, enabling natural language task management.</p>
+</div>
+
+## Features
+
+* **Complete Todoist API Integration**: Access to the full Todoist REST API v2 through natural language
+* **Tasks Management**: Create, update, close, reopen, and delete tasks using conversational language
+* **Project Management**: Create and manage projects and sections
+* **Comments Support**: Add and manage comments on tasks and projects
+* **Label Management**: Create and manage personal and shared labels
+
+## Configuration
+
+You'll need a Todoist API token to use this MCP server.
+
+### Getting a Todoist API Token
+
+1. Log in to your Todoist account
+2. Navigate to Settings → Integrations
+3. Find your API token under "Developer"
+
+### Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "todoist": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "todoist-mcp"
+      ],
+      "env": {
+        "API_KEY": "your_todoist_api_token_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Tasks
+
+- `get_tasks`: Retrieve tasks with optional filtering
+- `create_task`: Create a new task with various attributes
+- `get_task`: Get a specific task by ID
+- `update_task`: Update an existing task
+- `close_task`: Mark a task as complete
+- `reopen_task`: Reopen a completed task
+- `delete_task`: Delete a task
+
+### Projects
+
+- `get_projects`: Get all projects
+- `create_project`: Create a new project
+- `get_project`: Get a specific project by ID
+- `update_project`: Update an existing project
+- `delete_project`: Delete a project
+- `get_collaborators`: Get all collaborators for a project
+
+### Sections
+
+- `get_sections`: Get all sections or filter by project
+- `create_section`: Create a new section
+- `get_section`: Get a specific section by ID
+- `update_section`: Update a section
+- `delete_section`: Delete a section
+
+### Comments
+
+- `get_comments`: Get comments for a project or task
+- `create_comment`: Create a new comment
+- `get_comment`: Get a specific comment by ID
+- `update_comment`: Update a comment
+- `delete_comment`: Delete a comment
+
+### Labels
+
+- `get_labels`: Get all personal labels
+- `create_label`: Create a new personal label
+- `get_label`: Get a personal label by ID
+- `update_label`: Update a personal label
+- `delete_label`: Delete a personal label
+- `get_shared_labels`: Get all shared labels
+- `rename_shared_label`: Rename a shared label
+- `remove_shared_label`: Remove a shared label
+
+### Utilities
+
+- `utils_get_colors`: Get available colors for projects, labels, and filters
+
+## Example Usage
+
+Ask your AI assistant (like Claude) questions such as:
+
+```
+"What tasks do I have due today?"
+"Create a task to review the quarterly report by next Friday"
+"Make a new project called 'Home Renovation'"
+"Add a comment to my meeting prep task"
+"Show me all my high priority tasks"
+"Create a label for 'Urgent' tasks with a red color"
+"What projects do I have in my Todoist?"
+"Mark my dentist appointment task as complete"
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project and run inspector
+npm run build && npx @modelcontextprotocol/inspector -e API_KEY=YOUR_API_KEY_HERE node dist/index.js
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Issues and Support
+
+If you encounter any issues or need support, please file an issue on the GitHub repository.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { config, log } from './utils/helpers.js';
+import { version } from './utils/version.js';
+import { ALL_HANDLERS, ALL_TOOLS } from "./tools.js";
+const server = new Server({
+    name: 'todoist-mcp',
+    version
+}, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: ALL_TOOLS };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    log('Tool call: ', toolName);
+    try {
+        const handler = ALL_HANDLERS[toolName];
+        if (!handler) {
+            throw new Error(`Unknown tool: ${toolName}`);
+        }
+        return await handler(request);
+    }
+    catch (error) {
+        log('Error handling tool call:', error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                }
+            ],
+            isError: true,
+        };
+    }
+});
+export async function main() {
+    if (!config.API_KEY || config.API_KEY.length === 0) {
+        log('Missing required configuration: TODOIST_API_TOKEN');
+        process.exit(1);
+    }
+    try {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        log('Server connected and running');
+    }
+    catch (error) {
+        log('Fatal error:', error);
+        process.exit(1);
+    }
+}
+main().then();

package/dist/tools/comments.d.ts

@@ -0,0 +1,4 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ToolHandlers } from '../utils/types.js';
+export declare const COMMENTS_TOOLS: Tool[];
+export declare const COMMENT_HANDLERS: ToolHandlers;

package/dist/tools/comments.js

@@ -0,0 +1,141 @@
+import z from 'zod';
+import { createApiHandler } from "../utils/handlers.js";
+export const COMMENTS_TOOLS = [
+    {
+        name: 'get_comments',
+        description: 'Get all comments from Todoist, must be provided or `project_id` or `task_id`',
+        inputSchema: {
+            type: "object",
+            required: [],
+            properties: {
+                project_id: {
+                    type: "string",
+                    description: 'ID of the project used to filter comments'
+                },
+                task_id: {
+                    type: "string",
+                    description: 'ID of the task used to filter comments'
+                }
+            }
+        }
+    },
+    {
+        name: 'create_comment',
+        description: 'Create a new comment in Todoist, must be provided or `project_id` or `task_id`',
+        inputSchema: {
+            type: "object",
+            required: ["content"],
+            properties: {
+                task_id: {
+                    type: "string",
+                    description: 'Comment\'s task ID (for task comments)'
+                },
+                project_id: {
+                    type: "string",
+                    description: 'Comment\'s project ID (for project comments)'
+                },
+                content: {
+                    type: "string",
+                    description: 'Comment markdown-formatted text and hyperlinks'
+                },
+                // attachment: {
+                //     type: "object",
+                //     description: 'Object for attachment object'
+                // }
+            }
+        }
+    },
+    {
+        name: 'get_comment',
+        description: 'Get a comment from Todoist by ID',
+        inputSchema: {
+            type: "object",
+            required: ["id"],
+            properties: {
+                id: {
+                    type: "string",
+                    description: 'ID of the comment to retrieve'
+                }
+            }
+        }
+    },
+    {
+        name: 'update_comment',
+        description: 'Update a comment in Todoist',
+        inputSchema: {
+            type: "object",
+            required: ["id", "content"],
+            properties: {
+                id: {
+                    type: "string",
+                    description: 'ID of the comment to update'
+                },
+                content: {
+                    type: "string",
+                    description: 'New content, markdown-formatted text and hyperlinks'
+                }
+            }
+        }
+    },
+    {
+        name: 'delete_comment',
+        description: 'Delete a comment in Todoist',
+        inputSchema: {
+            type: "object",
+            required: ["id"],
+            properties: {
+                id: {
+                    type: "string",
+                    description: 'ID of the comment to delete'
+                }
+            }
+        }
+    }
+];
+export const COMMENT_HANDLERS = {
+    get_comments: createApiHandler({
+        schemaShape: {
+            project_id: z.string().optional(),
+            task_id: z.string().optional(),
+        },
+        method: 'GET',
+        path: '/comments',
+        errorPrefix: 'Failed to get comments',
+    }),
+    create_comment: createApiHandler({
+        schemaShape: {
+            task_id: z.string().optional(),
+            project_id: z.string().optional(),
+            content: z.string(),
+            // attachment: z.object({}).optional(),
+        },
+        method: 'POST',
+        path: '/comments',
+        errorPrefix: 'Failed to create comment',
+    }),
+    get_comment: createApiHandler({
+        schemaShape: {
+            id: z.string(),
+        },
+        method: 'GET',
+        path: '/comments/{id}',
+        errorPrefix: 'Failed to get comment',
+    }),
+    update_comment: createApiHandler({
+        schemaShape: {
+            id: z.string(),
+            content: z.string(),
+        },
+        method: 'POST',
+        path: '/comments/{id}',
+        errorPrefix: 'Failed to update comment',
+    }),
+    delete_comment: createApiHandler({
+        schemaShape: {
+            id: z.string(),
+        },
+        method: 'DELETE',
+        path: '/comments/{id}',
+        errorPrefix: 'Failed to delete comment',
+    }),
+};

package/dist/tools/create_task.d.ts

@@ -0,0 +1,4 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ToolHandlers } from '../utils/types.js';
+export declare const CREATE_TASK_TOOLS: Tool[];
+export declare const CREATE_TASK_HANDLER: ToolHandlers;

package/dist/tools/create_task.js

@@ -0,0 +1,179 @@
+import { log, todoistApi } from '../utils/helpers.js';
+import z from 'zod';
+export const CREATE_TASK_TOOLS = [
+    {
+        name: 'create_task',
+        description: 'Create a new task in Todoist with various parameters',
+        inputSchema: {
+            type: "object",
+            properties: {
+                content: {
+                    type: "string",
+                    description: 'Task content. This value may contain markdown-formatted text and hyperlinks.',
+                },
+                description: {
+                    type: "string",
+                    description: 'A description for the task. This value may contain markdown-formatted text and hyperlinks.',
+                },
+                project_id: {
+                    type: "string",
+                    description: 'Task project ID. If not set, task is put to user\'s Inbox.',
+                },
+                section_id: {
+                    type: "string",
+                    description: 'ID of section to put task into.',
+                },
+                parent_id: {
+                    type: "string",
+                    description: 'Parent task ID.',
+                },
+                order: {
+                    type: "integer",
+                    description: 'Non-zero integer value used by clients to sort tasks under the same parent.',
+                },
+                labels: {
+                    type: "array",
+                    items: {
+                        type: "string"
+                    },
+                    description: 'The task\'s labels (a list of names that may represent either personal or shared labels).',
+                },
+                priority: {
+                    type: "integer",
+                    description: 'Task priority from 1 (normal) to 4 (urgent).',
+                    enum: [1, 2, 3, 4]
+                },
+                due_string: {
+                    type: "string",
+                    description: 'Human defined task due date (ex.: "next Monday", "Tomorrow"). Value is set using local (not UTC) time.',
+                },
+                due_date: {
+                    type: "string",
+                    description: 'Specific date in YYYY-MM-DD format relative to user\'s timezone.',
+                },
+                due_datetime: {
+                    type: "string",
+                    description: 'Specific date and time in RFC3339 format in UTC.',
+                },
+                due_lang: {
+                    type: "string",
+                    description: '2-letter code specifying language in case due_string is not written in English.',
+                },
+                assignee_id: {
+                    type: "string",
+                    description: 'The responsible user ID (only applies to shared tasks).',
+                },
+                duration: {
+                    type: "integer",
+                    description: 'A positive (greater than zero) integer for the amount of duration_unit the task will take.',
+                },
+                duration_unit: {
+                    type: "string",
+                    description: 'The unit of time that the duration field represents. Must be either minute or day.',
+                    enum: ["minute", "day"]
+                },
+                deadline_date: {
+                    type: "string",
+                    description: 'Specific date in YYYY-MM-DD format relative to user\'s timezone.',
+                },
+                deadline_lang: {
+                    type: "string",
+                    description: '2-letter code specifying language of deadline.',
+                }
+            },
+            required: ["content"]
+        }
+    }
+];
+export const CREATE_TASK_HANDLER = {
+    'create_task': async (request) => {
+        try {
+            const args = createTaskArgsSchema.parse(request.params.arguments);
+            const newTask = await handleCreateTask(args);
+            return {
+                toolResult: {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(newTask, null, 2)
+                        }],
+                },
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to create task: ${errorMessage}`);
+        }
+    }
+};
+const createTaskArgsSchema = z.object({
+    content: z.string(),
+    description: z.string().optional(),
+    project_id: z.string().optional(),
+    section_id: z.string().optional(),
+    parent_id: z.string().optional(),
+    order: z.number().int().optional(),
+    labels: z.array(z.string()).optional(),
+    priority: z.number().int().min(1).max(4).optional(),
+    due_string: z.string().optional(),
+    due_date: z.string().optional(),
+    due_datetime: z.string().optional(),
+    due_lang: z.string().optional(),
+    assignee_id: z.string().optional(),
+    duration: z.number().int().positive().optional(),
+    duration_unit: z.enum(["minute", "day"]).optional(),
+    deadline_date: z.string().optional(),
+    deadline_lang: z.string().optional()
+});
+async function handleCreateTask(args) {
+    log('Creating task with args:', JSON.stringify(args, null, 2));
+    try {
+        // Create task data object with the parameters
+        const taskData = {
+            content: args.content
+        };
+        // Add optional parameters directly using the API field names (snake_case)
+        if (args.description)
+            taskData.description = args.description;
+        if (args.project_id)
+            taskData.project_id = args.project_id;
+        if (args.section_id)
+            taskData.section_id = args.section_id;
+        if (args.parent_id)
+            taskData.parent_id = args.parent_id;
+        if (args.order)
+            taskData.order = args.order;
+        if (args.labels)
+            taskData.labels = args.labels;
+        if (args.priority)
+            taskData.priority = args.priority;
+        if (args.due_string)
+            taskData.due_string = args.due_string;
+        if (args.due_date)
+            taskData.due_date = args.due_date;
+        if (args.due_datetime)
+            taskData.due_datetime = args.due_datetime;
+        if (args.due_lang)
+            taskData.due_lang = args.due_lang;
+        if (args.assignee_id)
+            taskData.assignee_id = args.assignee_id;
+        // Handle duration object
+        if (args.duration && args.duration_unit) {
+            taskData.duration = {
+                amount: args.duration,
+                unit: args.duration_unit
+            };
+        }
+        if (args.deadline_date)
+            taskData.deadline_date = args.deadline_date;
+        if (args.deadline_lang)
+            taskData.deadline_lang = args.deadline_lang;
+        // Make direct POST request to /tasks endpoint
+        const newTask = await todoistApi.post('/tasks', taskData);
+        // Return the response directly from the API
+        return newTask;
+    }
+    catch (error) {
+        log('Error creating task:', error);
+        throw error;
+    }
+}

package/dist/tools/example.d.ts

@@ -0,0 +1,14 @@
+import { ToolHandlers } from '../utils/types.js';
+export declare const EXAMPLE_TOOLS: {
+    [x: string]: unknown;
+    name: string;
+    inputSchema: {
+        [x: string]: unknown;
+        type: "object";
+        properties?: {
+            [x: string]: unknown;
+        } | undefined;
+    };
+    description?: string | undefined;
+}[];
+export declare const EXAMPLE_HANDLERS: ToolHandlers;

package/dist/tools/example.js

@@ -0,0 +1,99 @@
+import { log, todoistApi } from '../utils/helpers.js';
+import z from 'zod';
+// Task list tool definition
+const GET_TASKS_TOOL = {
+    name: 'todoist_get_tasks',
+    description: 'Get a list of tasks from Todoist with various filters',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            project_id: {
+                type: 'string',
+                description: 'Filter tasks by project ID (optional)'
+            },
+            filter: {
+                type: 'string',
+                description: 'Natural language filter like "today", "tomorrow", "next week", "priority 1", "overdue" (optional)'
+            },
+            priority: {
+                type: 'number',
+                description: 'Filter by priority level (1-4) (optional)',
+                enum: [1, 2, 3, 4]
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum number of tasks to return (optional)',
+                default: 10
+            }
+        }
+    }
+};
+// Export all tools
+export const EXAMPLE_TOOLS = [GET_TASKS_TOOL];
+// Input validation schema using zod
+const getTasksArgsSchema = z.object({
+    project_id: z.string().optional(),
+    filter: z.string().optional(),
+    priority: z.number().min(1).max(4).optional(),
+    limit: z.number().positive().optional()
+});
+// Handler function implementation
+async function handleGetTasks(args) {
+    const { project_id, filter, priority, limit } = args;
+    log('Getting tasks', project_id ? `for project ${project_id}` : '', filter ? `with filter: ${filter}` : '', priority ? `with priority: ${priority}` : '', limit ? `with limit: ${limit}` : '');
+    try {
+        // Get tasks with filtering from API
+        const tasks = await todoistApi.getTasks({
+            projectId: project_id,
+            filter: filter
+        });
+        let filteredTasks = tasks.results;
+        if (priority) {
+            filteredTasks = filteredTasks.filter((task) => task.priority === priority);
+        }
+        // Apply limit if specified
+        if (limit && limit > 0) {
+            filteredTasks = filteredTasks.slice(0, limit);
+        }
+        // Return formatted task data
+        return filteredTasks.map(task => ({
+            id: task.id,
+            content: task.content,
+            project_id: task.projectId,
+            priority: task.priority,
+            due: task.due,
+            url: task.url,
+            labels: task.labels,
+            completed: task.isCompleted,
+            created_at: task.createdAt
+        }));
+    }
+    catch (error) {
+        log('Error fetching tasks:', error);
+        throw error;
+    }
+}
+// Export handlers
+export const EXAMPLE_HANDLERS = {
+    'todoist_get_tasks': async (request) => {
+        try {
+            // Parse and validate arguments
+            const args = getTasksArgsSchema.parse(request.params.arguments);
+            // Get tasks with all filters applied
+            const tasks = await handleGetTasks(args);
+            // Return formatted response
+            return {
+                toolResult: {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(tasks, null, 2)
+                        }],
+                },
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to get tasks: ${errorMessage}`);
+        }
+    }
+};

package/dist/tools/example.test.d.ts

@@ -0,0 +1 @@
+export {};