# abhiz123/todoist-mcp-server architecture

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

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

## Overview

Todoist MCP Server exposes Todoist task operations as MCP tools for a client such as Claude. The principal workflow is a client tool request, server-side dispatch and validation, then a Todoist API action and a text response. Search-based update, completion, and deletion first retrieve tasks and match task names; retrieval also applies filters. These responsibilities are implemented in one source file, so the graph separates runtime roles without implying separate modules. The README documents the full tool set; source excerpts show the key calls, but omit some handler details.

Main entry points: [`src/index.ts`](https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_stdio["stdio transport<br/>[index.ts]"]
  node_server["MCP server<br/>[index.ts]"]
  node_tooldefs["Tool definitions<br/>[index.ts]"]
  node_dispatch["Request dispatch<br/>[index.ts]"]
end

subgraph group_tasks["Task Operations"]
  node_taskops["Task handlers<br/>[index.ts]"]
  node_searchfilter["Search and filtering<br/>[index.ts]"]
  node_todoist["Todoist API"]
end

node_claude(("Claude / MCP client"))

node_claude -->|"sends MCP requests"| node_stdio
node_stdio -->|"connects transport"| node_server
node_server -->|"lists tools"| node_tooldefs
node_server -->|"dispatches calls"| node_dispatch
node_dispatch -->|"routes tool calls"| node_taskops
node_taskops -->|"matches and filters"| node_searchfilter
node_taskops -->|"creates and mutates tasks"| node_todoist
node_searchfilter -->|"retrieves tasks"| node_todoist

click node_stdio "https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts"
click node_server "https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts"
click node_tooldefs "https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts"
click node_dispatch "https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts"
click node_taskops "https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts"
click node_searchfilter "https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stdio,node_server,node_tooldefs,node_dispatch,node_claude toneBlue
class node_taskops,node_searchfilter,node_todoist toneAmber
```

## Components

### MCP Runtime

- [stdio transport](https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts): `src/index.ts`
- [MCP server](https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts): `src/index.ts`
- [Tool definitions](https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts): `src/index.ts`
- [Request dispatch](https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts): `src/index.ts`

### Task Operations

- [Task handlers](https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts): `src/index.ts`
- [Search and filtering](https://github.com/abhiz123/todoist-mcp-server/blob/main/src/index.ts): `src/index.ts`
- **Todoist API**

### Other components

- **Claude / MCP client**

## Connections

- Claude / MCP client → stdio transport: sends MCP requests (evidence: `README.md`)
- stdio transport → MCP server: connects transport (evidence: `src/index.ts`)
- MCP server → Tool definitions: lists tools (evidence: `src/index.ts`)
- MCP server → Request dispatch: dispatches calls (evidence: `src/index.ts`)
- Request dispatch → Task handlers: routes tool calls (evidence: `src/index.ts`)
- Task handlers → Search and filtering: matches and filters (evidence: `src/index.ts`)
- Task handlers → Todoist API: creates and mutates tasks (evidence: `src/index.ts`)
- Search and filtering → Todoist API: retrieves tasks (evidence: `src/index.ts`)