Weekend Project • AI • Completed
Todoist MCP Server
A comprehensive Model Context Protocol (MCP) server for Todoist API integration with AI assistants. Provides 32 strongly-typed tools for complete task management through natural language interactions.
Built with
TypeScript •Node.js •MCP •Axios •Zod •Jest
Key Features
0132 fully-typed MCP tools covering complete Todoist API
02Natural language quick-add: "Pay rent tomorrow 9am #Finance p1"
03Smart rate limiting with exponential backoff (450 req/15min)
0492% test coverage with 150+ unit/integration tests
05Zero boilerplate setup - works via stdin/stdout JSON-RPC
Overview
Todoist MCP Server bridges the gap between AI assistants and productivity workflows by providing seamless Todoist integration through the Model Context Protocol. This server enables natural language task management, allowing users to create, manage, and track tasks across projects using conversational AI interfaces like Claude, Cursor, and other MCP-compatible clients.
Features
• Complete CRUD operations for projects, tasks, sections, and labels
• Natural language task creation with intelligent parsing
• Productivity statistics and completion tracking
• Comments and collaboration features
• Rate-limit smart handling with automatic retries
• Cross-platform compatibility (VS Code, Cursor, Claude Desktop)
• Docker support for containerized deployments
• TypeScript-first with end-to-end type safety
Technical Details
Architecture
Built on Model Context Protocol (MCP) specification using JSON-RPC 2.0 over stdio. Core tool handlers provide strongly-typed Todoist API operations with Axios HTTP client, Zod schema validation, and comprehensive error handling.
Challenges
• Implementing robust rate limiting for Todoist API constraints
• Designing intuitive natural language parsing for task creation
• Ensuring type safety across 32 different API endpoints
• Managing async operations and error handling in MCP context
• Creating comprehensive test coverage for real API interactions
Solutions
• Developed smart rate limiting with exponential backoff and request queuing
• Implemented intelligent text parsing for natural language task input
• Used Zod schemas for runtime type validation and API response parsing
• Built comprehensive error handling with meaningful user feedback
• Created 150+ tests including integration tests with real Todoist Pro API
Key Learnings
• Deep understanding of Model Context Protocol specification
• Advanced TypeScript patterns for API client architecture
• Rate limiting strategies for third-party API integration
• Comprehensive testing strategies for external API dependencies
• JSON-RPC protocol implementation and best practices
Impact
Built in
3 hours
• MIT licensed with comprehensive documentation
• 92% test coverage with battle-tested reliability
• Support for 10+ AI assistant platforms
• API v1 compliant with 36/36 integration tests passing