todoist-mcp 1.2.4 → 1.3.1

package/README.md

@@ -32,24 +32,43 @@ You'll need a Todoist API token to use this MCP server.
 2. Navigate to Settings → Integrations
 3. Find your API token under "Developer"
 
-### Usage with Claude Desktop
+### Usage
 
-Add to your `claude_desktop_config.json`:
+Add to `mcpServers` in your platform config:
 
 ```json
-{
-    "mcpServers": {
-        "todoist": {
-            "command": "npx",
-            "args": ["-y", "todoist-mcp"],
-            "env": {
-                "API_KEY": "your_todoist_api_token_here"
-            }
-        }
-    }
+"todoist": {
+    "command": "npx",
+    "args": ["-y", "todoist-mcp"],
+    "env": { "API_KEY": "your_todoist_api_token" }
 }
 ```
 
+| Platform | Config |
+|----------|--------|
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\` (Windows) |
+| Claude Code | `.mcp.json` — `claude mcp add --transport stdio --scope project --env API_KEY=token todoist -- npx -y todoist-mcp` |
+| Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
+| Codex | `~/.codex/config.toml` or `.codex/config.toml` — see example below |
+| Gemini CLI | `~/.gemini/settings.json` — `gemini mcp add -e API_KEY=token todoist npx -y todoist-mcp` |
+
+**Codex** — CLI:
+
+```bash
+codex mcp add todoist --env API_KEY=your_token -- npx -y todoist-mcp
+```
+
+Or add to `config.toml`:
+
+```toml
+[mcp_servers.todoist]
+command = "npx"
+args = ["-y", "todoist-mcp"]
+
+[mcp_servers.todoist.env]
+API_KEY = "your_todoist_api_token"
+```
+
 ## Available Tools
 
 ### Tasks

package/dist/tools/tasks.js

@@ -48,21 +48,29 @@ const create_fields = {
 };
 createApiHandler({
     name: 'get_tasks_list',
-    description: 'Get tasks list from Todoist',
+    description: 'Get tasks list from Todoist. For advanced filtering use get_tasks_by_filter tool',
     schemaShape: {
         project_id: z.string().optional().describe('Filter by project'),
         section_id: z.string().optional().describe('Filter by section'),
         label: z.string().optional().describe('Filter by label'),
-        filter: z
-            .string()
-            .optional()
-            .describe('Natural language english filter like "search: keyword", "today", "date before: +4 hours", "date after: May 5", "no date", "no time", "overdue", "7 days & @waiting", "created before: -365 days", "assigned to: person", "added by: me", "#Project & !assigned", "subtask", "!subtask", "P1 | P2", "today & @email", "@work | @office", "(today | overdue) & #Work", "all & 7 days", "!assigned", "Today & !#Work"'),
         ids: z.string().optional().describe('Comma-separated list of task IDs'),
         limit: z.number().optional().default(50),
     },
     method: 'GET',
     path: '/tasks',
 });
+createApiHandler({
+    name: 'get_tasks_by_filter',
+    description: 'Get tasks from Todoist using filter language. Use for queries like "today", "overdue", "P1", date-based filters, label/project filters in query syntax',
+    schemaShape: {
+        query: z
+            .string()
+            .describe('Todoist filter query. Examples: "today", "overdue", "today | overdue", "no date", "no time", "P1 | P2", "7 days & @waiting", "created before: -365 days", "assigned to: person", "added by: me", "#Project & !assigned", "subtask", "!subtask", "today & @email", "@work | @office", "(today | overdue) & #Work", "all & 7 days", "!assigned", "search: keyword"'),
+        limit: z.number().optional().default(50),
+    },
+    method: 'GET',
+    path: '/tasks/filter',
+});
 createBatchApiHandler({
     name: 'create_tasks',
     description: 'Create new tasks in Todoist',
@@ -191,18 +199,20 @@ createSyncApiHandler({
         return { valid: true };
     },
 });
-createHandler('get_completed_tasks', 'Get completed tasks from Todoist with filtering options', {
-    project_id: z.string().optional().describe('Filter by specific project ID'),
-    section_id: z.string().optional().describe('Filter by specific section ID'),
-    parent_id: z.string().optional().describe('Filter by specific parent task ID'),
+createHandler('get_completed_tasks', 'Get completed tasks from Todoist with filtering options. Date range limited to 3 months max.', {
     since: z
         .string()
-        .optional()
-        .describe('Return tasks completed since this date (YYYY-MM-DD format)'),
+        .describe('Start of completion date range (ISO 8601 date-time, e.g. "2025-01-01T00:00:00Z")'),
     until: z
+        .string()
+        .describe('End of completion date range (ISO 8601 date-time, e.g. "2025-03-31T23:59:59Z")'),
+    project_id: z.string().optional().describe('Filter by specific project ID'),
+    section_id: z.string().optional().describe('Filter by specific section ID'),
+    parent_id: z.string().optional().describe('Filter by specific parent task ID'),
+    cursor: z
         .string()
         .optional()
-        .describe('Return tasks completed until this date (YYYY-MM-DD format)'),
+        .describe('Cursor for pagination (from next_cursor in previous response)'),
     limit: z
         .number()
         .int()
@@ -211,8 +221,6 @@ createHandler('get_completed_tasks', 'Get completed tasks from Todoist with filt
         .optional()
         .default(50)
         .describe('Number of tasks to return (max 200)'),
-    offset: z.number().int().min(0).optional().describe('Offset for pagination'),
-    annotation_type: z.string().optional().describe('Filter by annotation type'),
 }, async (args) => {
     const params = {};
     Object.entries(args).forEach(([key, value]) => {
@@ -220,11 +228,5 @@ createHandler('get_completed_tasks', 'Get completed tasks from Todoist with filt
             params[key] = typeof value === 'number' ? value.toString() : value;
         }
     });
-    const response = await todoistApi.getCompletedTasks(params);
-    return {
-        completed_tasks: response.items || [],
-        projects: response.projects || {},
-        sections: response.sections || {},
-        total: response.items?.length || 0,
-    };
+    return todoistApi.getCompletedTasks(params);
 });

package/dist/utils/TodoistClient.d.ts

@@ -31,7 +31,7 @@ export declare class TodoistClient {
      */
     sync(commands: Array<SyncCommand>): Promise<any>;
     /**
-     * Get completed tasks using Sync API
+     * Get completed tasks via REST API
      * @param params - Query parameters for filtering completed tasks
      * @returns API response data with completed tasks
      */

package/dist/utils/TodoistClient.js

@@ -1,8 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { v4 as uuidv4 } from 'uuid';
 import { log } from './helpers.js';
-const API_BASE_URL = 'https://api.todoist.com/rest/v2';
-const API_SYNC_BASE_URL = 'https://api.todoist.com/sync/v9';
+const API_BASE_URL = 'https://api.todoist.com/api/v1';
 export class TodoistClient {
     apiToken;
     constructor(apiToken) {
@@ -53,7 +52,12 @@ export class TodoistClient {
             method: 'GET',
             headers: this.getHeaders(),
         });
-        return this.handleResponse(response);
+        const data = await this.handleResponse(response);
+        // API v1 wraps list responses in { results: [...] }
+        if (data && typeof data === 'object' && Array.isArray(data.results)) {
+            return data.results;
+        }
+        return data;
     }
     /**
      * Make a POST request to Todoist API
@@ -91,7 +95,7 @@ export class TodoistClient {
      * @returns API response data
      */
     async sync(commands) {
-        const url = `${API_SYNC_BASE_URL}/sync`;
+        const url = `${API_BASE_URL}/sync`;
         log(`Making SYNC request to: ${url} with commands:`, JSON.stringify(commands, null, 2));
         const response = await fetch(url, {
             method: 'POST',
@@ -101,28 +105,11 @@ export class TodoistClient {
         return this.handleResponse(response);
     }
     /**
-     * Get completed tasks using Sync API
+     * Get completed tasks via REST API
      * @param params - Query parameters for filtering completed tasks
      * @returns API response data with completed tasks
      */
     async getCompletedTasks(params = {}) {
-        const url = `${API_SYNC_BASE_URL}/completed/get_all`;
-        log(`Making completed tasks request to: ${url} with params:`, JSON.stringify(params, null, 2));
-        const formData = new URLSearchParams();
-        for (const [key, value] of Object.entries(params)) {
-            if (value) {
-                formData.append(key, value);
-            }
-        }
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: {
-                Authorization: `Bearer ${this.apiToken}`,
-                'Content-Type': 'application/x-www-form-urlencoded',
-                'X-Request-Id': uuidv4(),
-            },
-            body: formData.toString(),
-        });
-        return this.handleResponse(response);
+        return this.get('/tasks/completed/by_completion_date', params);
     }
 }

package/dist/utils/version.d.ts

@@ -1 +1 @@
-export declare const version = "1.2.4";
+export declare const version = "1.3.1";

package/dist/utils/version.js

@@ -1,2 +1,2 @@
 // Auto-generated file, do not edit
-export const version = '1.2.4';
+export const version = '1.3.1';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "todoist-mcp",
-    "version": "1.2.4",
+    "version": "1.3.1",
     "description": "Todoist MCP Server",
     "type": "module",
     "main": "dist/index.js",
@@ -61,4 +61,4 @@
         "vite": "^5.0.0",
         "vitest": "^1.0.0"
     }
-}
+}