How mikemc/todoist-mcp-server works
Project Type and Purpose
• Type: A single-service “MCP server” (micro-tool provider) that integrates with the Todoist REST API
• Purpose: Expose Todoist entities (projects, sections, tasks) as Claude MCP tools via a Python process launched by the UV CLI
File Structure
Top-level
• main.py ← entry point & MCP protocol handler
• pyproject.toml ← package metadata & dependencies
• uv.lock ← locked UV dependencies
src/
• api.py ← thin wrapper over Todoist Python API
• projects.py ← “projects” tool implementations
• sections.py ← “sections” tool implementations
• tasks.py ← task-related tool implementations
• tasks_sync.py ← sync utilities or batch operations
• utils.py ← shared helper functions
README for Insights
• Describes use of UV to launch main.py under Claude Desktop’s mcpServers
• Lists all available tools and their mappings (e.g., todoist_get_projects)
• Requires an environment variable TODOIST_API_TOKEN for authentication
Main Components
A. External Client
– Claude Desktop (MCP client)
B. Launch Mechanism
– UV CLI (“uv run main.py”)
C. MCP Server Process
1. Protocol Handler (in main.py)
• Registers tools via mcp.tool() decorator
• Receives JSON-RPC calls over STDIO or pipes
2. Tool Registry
• Dispatches calls to specific tool functions
3. Tool Modules
• projects.py, sections.py, tasks.py, tasks_sync.py
4. Utility Layer
• utils.py for shared logic (e.g., input validation)
5. API Client Layer
• api.py wraps Todoist Python REST client
D. External Service
– Todoist REST API (HTTPS endpoints)
E. Environment
– Environment variable TODOIST_API_TOKEN
Relationships & Data-Flow
1. Claude Desktop → (STDIO/JSON-RPC) → Protocol Handler
2. Protocol Handler → (in‐process call) → Tool Registry → Specific Tool Function
3. Tool Function → (library call) → API Client Layer
4. API Client → (HTTP request) → Todoist REST API
5. Todoist REST API → (HTTP response) → API Client → Tool → Protocol Handler → Claude Desktop
Architectural Patterns and Principles
• Single-process micro-tool server
• Clear separation of concerns: protocol handling, tool logic, API communication, utilities
• Dependency injection of API token via environment
• Modularity: one module per resource (projects/sections/tasks)
• Stateless HTTP calls to external service