Todoist MCP Server

Instructions

Args:
    content: The task content/title
    description: Detailed description of the task
    project_id: Project ID to add the task to
    section_id: Section ID within the project
    parent_id: Parent task ID (for subtasks)
    labels: List of label names
    priority: Priority from 1 (normal) to 4 (urgent)
    due_string: Human readable due date (e.g., 'tomorrow', 'next Monday')
    due_date: ISO 8601 formatted due date

Implementation Reference

• todoist_mcp/server.py:102-146 (handler)

  The primary MCP tool handler for 'create_task'. Decorated with @mcp.tool() for automatic registration and schema generation from parameters. Delegates to TodoistClient.create_task and formats the response.

  @mcp.tool()
  async def create_task(
      content: str,
      description: str = "",
      project_id: Optional[str] = None,
      section_id: Optional[str] = None,
      parent_id: Optional[str] = None,
      labels: Optional[List[str]] = None,
      priority: int = 1,
      due_string: Optional[str] = None,
      due_date: Optional[str] = None
  ) -> str:
      """Create a new task in Todoist.
      
      Args:
          content: The task content/title
          description: Detailed description of the task
          project_id: Project ID to add the task to
          section_id: Section ID within the project
          parent_id: Parent task ID (for subtasks)
          labels: List of label names
          priority: Priority from 1 (normal) to 4 (urgent)
          due_string: Human readable due date (e.g., 'tomorrow', 'next Monday')
          due_date: ISO 8601 formatted due date
      """
      _check_client()
      
      task = await todoist_client.create_task(
          content=content,
          description=description,
          project_id=project_id,
          section_id=section_id,
          parent_id=parent_id,
          labels=labels or [],
          priority=priority,
          due_string=due_string,
          due_date=due_date
      )
      
      return (
          f"Task created successfully!\n"
          f"ID: {task.id}\n"
          f"Title: {task.content}\n"
          f"URL: {task.url}"
      )

• todoist_mcp/client.py:101-136 (helper)

  Helper method in TodoistClient that constructs the payload and makes the HTTP POST request to Todoist API endpoint /tasks to create the task.

  async def create_task(self, 
                       content: str,
                       description: str = "",
                       project_id: Optional[str] = None,
                       section_id: Optional[str] = None,
                       parent_id: Optional[str] = None,
                       order: Optional[int] = None,
                       labels: Optional[List[str]] = None,
                       priority: int = 1,
                       due_string: Optional[str] = None,
                       due_date: Optional[str] = None) -> TodoistTask:
      """Create a new task."""
      payload = {
          "content": content,
          "description": description,
          "priority": priority
      }
      
      if project_id:
          payload["project_id"] = project_id
      if section_id:
          payload["section_id"] = section_id
      if parent_id:
          payload["parent_id"] = parent_id
      if order is not None:
          payload["order"] = order
      if labels:
          payload["labels"] = labels
      if due_string:
          payload["due_string"] = due_string
      if due_date:
          payload["due_date"] = due_date
      
      data = await self._request("POST", "/tasks", json=payload)
      return TodoistTask(**data)

• todoist_mcp/client.py:9-25 (schema)

  Pydantic model defining the TodoistTask structure, used for parsing API responses in create_task and other operations.

  class TodoistTask(BaseModel):
      """Represents a Todoist task."""
      id: str
      content: str
      description: str = ""
      is_completed: bool = False
      labels: List[str] = []
      priority: int = 1
      due_string: Optional[str] = None
      due_date: Optional[str] = None
      project_id: str = ""
      section_id: Optional[str] = None
      parent_id: Optional[str] = None
      order: int = 0
      url: str = ""
      created_at: str = ""

• todoist_mcp/server.py:102-102 (registration)

  The @mcp.tool() decorator registers the create_task function as an MCP tool with the name 'create_task' and auto-generates input schema from type hints.

  @mcp.tool()