Todoist MCP Server

Translates conversational task descriptions into structured Todoist API calls by parsing natural language for task content, due dates, priority levels, project assignments, and labels. Uses date recognition to convert phrases like 'tomorrow' or 'next Monday' into ISO format, and maps semantic priority descriptions (e.g., 'high', 'urgent') to Todoist's 1-4 priority scale. Implements MCP tool schema validation to ensure all parameters conform to Todoist API requirements before transmission.

Executes structured queries against Todoist's task database by translating natural language filters (e.g., 'tasks due today', 'overdue items in project X', 'high priority tasks') into Todoist API filter syntax. Supports filtering by due date ranges, project, label, priority, and completion status. Implements result limiting and pagination to prevent overwhelming response sizes. The server parses natural language date expressions and converts them to Todoist's filter query language before API submission.

Catches HTTP errors from Todoist API calls and translates them into user-friendly error messages that Claude can understand and communicate to users. Handles common error scenarios (invalid token, rate limiting, malformed requests, server errors) with appropriate error codes and descriptions. Implements retry logic for transient errors (5xx responses) and provides clear feedback for permanent errors (4xx responses).

Implements substring and fuzzy matching logic to identify tasks by partial or approximate names, reducing the need for exact task IDs. Uses case-insensitive matching and handles common variations (e.g., extra spaces, punctuation differences). Returns the best matching task when multiple candidates exist, with confidence scoring to help Claude disambiguate if needed.

Implements MCP server using stdio transport to communicate with Claude Desktop via standard input/output streams. Handles MCP protocol serialization/deserialization of JSON-RPC messages, tool invocation routing, and response formatting. Manages the lifecycle of the stdio connection and handles graceful shutdown on client disconnect.

Updates task properties (name, description, due date, priority, project, labels) by first performing partial name matching to locate the target task, then submitting attribute changes to the Todoist API. Uses fuzzy matching or substring search to identify tasks from incomplete descriptions, reducing the need for exact task IDs. Validates all updated attributes against Todoist API schema before submission and returns confirmation of changes applied.

Marks tasks as complete by first identifying them through partial name matching, then submitting completion status to the Todoist API. Implements fuzzy matching to locate tasks from incomplete or approximate descriptions, reducing friction in conversational workflows. Returns confirmation of completion status and task metadata to confirm the action succeeded.

Removes tasks from Todoist by first identifying them through partial name matching, then submitting deletion requests to the Todoist API. Implements fuzzy matching to locate tasks from incomplete descriptions. Provides confirmation feedback to acknowledge successful deletion and prevent accidental removals.

Implements the Model Context Protocol (MCP) server that translates Claude Desktop's tool invocations into Todoist REST API v2 calls via stdio transport. Acts as a protocol adapter layer that handles MCP request/response serialization, tool schema registration, and error handling. Uses TypeScript with type-safe tool definitions to ensure Claude's requests conform to Todoist API requirements before submission. Manages authentication via Todoist API token and handles all HTTP communication with Todoist's servers.

Defines and validates MCP tool schemas for all five task management operations (create, read, update, complete, delete) using TypeScript type definitions. Each tool schema specifies required and optional parameters, parameter types, and descriptions. The server registers these schemas with the MCP protocol, allowing Claude to discover available tools and their signatures. Validates incoming tool invocations against schemas before forwarding to Todoist API, preventing malformed requests.

Converts natural language date expressions (e.g., 'tomorrow', 'next Monday', 'this week', 'in 3 days') into ISO 8601 format required by Todoist API. Implements heuristic-based date parsing that understands relative date references and common English date patterns. Handles ambiguous dates by applying reasonable defaults (e.g., 'next week' defaults to Monday). Returns ISO-formatted date strings that conform to Todoist's due_date field requirements.

Translates semantic priority descriptions (e.g., 'high', 'urgent', 'low', 'normal') into Todoist's numeric priority scale (1-4, where 4 is highest). Implements bidirectional mapping so Claude can understand both natural language priority input and numeric priority output. Provides reasonable defaults for ambiguous priority references.

Manages Todoist API authentication by accepting API tokens via environment variables or configuration files and including them in HTTP Authorization headers for all API requests. Implements secure credential handling that prevents token exposure in logs or error messages. Validates token validity on server startup and provides clear error messages if authentication fails.