# mikemc/todoist-mcp-server architecture

> Architecture diagram of the GitHub repository mikemc/todoist-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mikemc/todoist-mcp-server
- Repository: https://github.com/mikemc/todoist-mcp-server

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client"
        Claude["Claude Desktop"]:::client
    end

    %% Launch Mechanism
    UV["UV CLI\n\"uv run main.py\""]:::cli

    %% Environment / Config
    subgraph "Environment"
        Env["TODOIST_API_TOKEN\n(env var)"]:::config
        PyProj["pyproject.toml"]:::config
        UVLock["uv.lock"]:::config
    end

    %% Server Process
    subgraph "MCP Server Process"
        Main["Protocol Handler & Tool Registry\n(main.py)"]:::internal
        subgraph "Tool Modules"
            Projects["Projects Tool\n(src/projects.py)"]:::internal
            Sections["Sections Tool\n(src/sections.py)"]:::internal
            Tasks["Tasks Tool\n(src/tasks.py)"]:::internal
            TasksSync["Tasks Sync Module\n(src/tasks_sync.py)"]:::internal
        end
        APIClient["API Client Layer\n(src/api.py)"]:::internal
        Utils["Utility Layer\n(src/utils.py)"]:::internal
    end

    %% External Service
    Todoist[(Todoist REST API)]:::external

    %% Data Flows
    Claude -->|"STDIO/JSON-RPC"| UV
    UV -->|"launch process"| Main
    Env -->|"injects token"| Main
    Main -->|"dispatch call"| Projects
    Main -->|"dispatch call"| Sections
    Main -->|"dispatch call"| Tasks
    Main -->|"dispatch call"| TasksSync
    Projects -->|"library call"| APIClient
    Sections -->|"library call"| APIClient
    Tasks -->|"library call"| APIClient
    TasksSync -->|"library call"| APIClient
    APIClient -->|"HTTP request"| Todoist
    Todoist -->|"HTTP response"| APIClient
    APIClient -->|"return data"| Projects
    Projects -->|"JSON-RPC response"| Main
    APIClient -->|"return data"| Sections
    Sections -->|"JSON-RPC response"| Main
    APIClient -->|"return data"| Tasks
    Tasks -->|"JSON-RPC response"| Main
    APIClient -->|"return data"| TasksSync
    TasksSync -->|"JSON-RPC response"| Main
    Main -->|"JSON-RPC response"| Claude

    %% Click Events
    click Main "https://github.com/mikemc/todoist-mcp-server/blob/main/main.py"
    click APIClient "https://github.com/mikemc/todoist-mcp-server/blob/main/src/api.py"
    click Projects "https://github.com/mikemc/todoist-mcp-server/blob/main/src/projects.py"
    click Sections "https://github.com/mikemc/todoist-mcp-server/blob/main/src/sections.py"
    click Tasks "https://github.com/mikemc/todoist-mcp-server/blob/main/src/tasks.py"
    click TasksSync "https://github.com/mikemc/todoist-mcp-server/blob/main/src/tasks_sync.py"
    click Utils "https://github.com/mikemc/todoist-mcp-server/blob/main/src/utils.py"
    click PyProj "https://github.com/mikemc/todoist-mcp-server/blob/main/pyproject.toml"
    click UVLock "https://github.com/mikemc/todoist-mcp-server/blob/main/uv.lock"

    %% Styles
    classDef client fill:#ffd,stroke:#333,stroke-width:1px
    classDef cli fill:#fdd,stroke:#333,stroke-width:1px
    classDef internal fill:#ddf,stroke:#333,stroke-width:1px
    classDef external fill:#dfd,stroke:#333,stroke-width:1px
    classDef config fill:#eee,stroke:#999,stroke-dasharray: 2 2,stroke-width:1px
```
