Todoist MCP Server

When designing or extending tools, follow these naming and design conventions:

Naming Conventions

• Use Action Verbs: Start names with find-, add-, manage-, or complete-.
• Use User Terminology: Use terms users understand (e.g., complete-tasks instead of close-tasks).

Design Best Practices

• Batch Support: Implement batch support when users commonly perform multiple related items at once.
• Smart Defaults: Use optional parameters and attempt to auto-detect user intent.
• Rich Responses: Always aim for a combination of structured data, human text, and suggested next steps.

Decision Logic

• Create a new tool when: It represents a distinct user workflow, cannot be elegantly extended, or has unique parameter requirements.
• Extend an existing tool when: The new functionality is closely related to the existing tool's purpose, can be handled with additional parameters, or follows the same workflow pattern.

Every tool in this project follows a strict TodoistTool interface defined in src/todoist-tool.ts. This contract ensures that the MCP server can correctly register tools, validate parameters using Zod, and handle execution logic consistently.

A tool must define:

• name: The unique identifier for the tool.
• description: A string describing what the tool does (used by the LLM).
• parameters: A Zod raw shape defining the input schema.
• annotations: Metadata including readOnlyHint, destructiveHint, and idempotentHint to guide the LLM on how to use the tool safely.
• execute: An asynchronous function that takes the parsed arguments and the TodoistApi client, returning a response containing textContent, structuredContent, or contentItems.

type TodoistTool<
    Params extends z.ZodRawShape,
    Output extends z.ZodRawShape = Record<string, never>,
> = {
    name: string
    description: string
    parameters: Params // Zod raw shape (NOT z.object)
    outputSchema?: Output // Zod raw shape; omit for tools that return only content blocks
    annotations: {
        readOnlyHint: boolean
        destructiveHint: boolean
        idempotentHint: boolean
    }
    _meta?: Record<string, unknown>
    execute: (
        args: z.infer<z.ZodObject<Params>>,
        client: TodoistApi,
    ) => Promise<{ 
        textContent?: string
        structuredContent?: z.infer<z.ZodObject<Output>>
        contentItems?: ContentBlock[] 
    }>
}

The Todoist MCP server uses a workflow-centric approach rather than a traditional API-centric approach. Instead of creating a tool for every single API endpoint (e.g., add-project, update-project, get-project), the server provides specialized workflow tools designed around user intent and batch operations.

Core Principles

• User Intent Over API Structure: Tools match how users work, not how the API is organized.
• Batch Operations: Tools support multiple items where logical (e.g., add-tasks accepts an array).
• Explicit Intent: Uses clear action verbs to reduce ambiguity for LLMs (e.g., add-projects vs update-projects).
• Universal Patterns: Unifies similar operations under a single tool (e.g., delete-object handles all entity types).
• Context-Aware Responses: Returns both structured data and human-readable text containing suggested next steps to maintain workflow momentum.

To connect the Todoist MCP server to clients like Claude Desktop or Cursor using the stdio transport, add a configuration entry to your mcp.json file.

Using npx (Recommended)

{
    "mcpServers": {
        "todoist-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": ["@doist/todoist-mcp"],
            "env": {
                "TODOIST_API_KEY": "your-todoist-token-here"
            }
        }
    }
}

Using a Local Installation

If you have cloned the repository locally, point the command to your local node binary and the dist/main.js file:

{
    "mcpServers": {
        "todoist-mcp-local": {
            "type": "stdio",
            "command": "node",
            "args": ["/Users/<your_user_name>/code/todoist-mcp/dist/main.js"],
            "env": {
                "TODOIST_API_KEY": "your-todoist-token-here"
            }
        }
    }
}