What is Todoist Mcp Python

todoist-mcp-python is a Model Context Protocol (MCP) server developed in Python that facilitates interaction between MCP Clients, such as Claude, and the Todoist API for task management using natural language.

Use cases

Use cases include adding tasks via voice commands, retrieving lists of tasks based on urgency, marking tasks as complete, and updating task priorities.

How to use

To use todoist-mcp-python, clone the repository from GitHub, configure your Claude settings to include the server, and ensure you have a valid Todoist API token set in your environment variables.

Key features

Key features include task creation, retrieval, management (updating, completing, and deleting tasks), and the ability to filter tasks based on various criteria.

Where to use

todoist-mcp-python can be used in personal task management, project management, and any application requiring natural language processing for task-related operations.

Todoist MCP Server

A Model Context Protocol (MCP) server that allows clients like Claude to interact with Todoist, enabling task management capabilities through natural language. The server acts as an intermediary between clients and the Todoist API, handling authentication, data transformation, and command processing. This is a Python version

Features

• Task Creation: Create new tasks with required content and optional attributes
• Task Retrieval: Get task by ID or list tasks with filtering options
• Task Management: Update task attributes, mark tasks as complete, delete tasks

Prerequisites

• Python 3.12
• uv
• A Todoist account and API token

How to get Todoist API Token

1. Login to your Todoist account
2. Go to User Settings -> Integrations -> Developer
3. Copy API token

Usage with Claude Desktop

Run via UVX (without cloning)

You can run the server directly from GitHub using UVX:

uvx --from https://github.com/Johnxjp/todoist-mcp-python.git mcp-server-todoist

Then add this configuration to your Claude settings:

{
  "mcpServers": {
    "todoist-server": {
      "command": "uvx",
      "args": [
        "--from", 
        "https://github.com/Johnxjp/todoist-mcp-python.git", 
        "mcp-server-todoist"
      ],
      "env": {
        "TODOIST_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Run from cloned repository

If you prefer to clone the repository, use these commands:

git clone [email protected]:Johnxjp/todoist-mcp-python.git

Then add to your Claude config file:

{
  "mcpServers": {
    "todoist-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "todoist_api_python",
        "mcp",
        "run",
        "/full/path/to/todoist_server.py"
      ],
      "env": {
        "TODOIST_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Available Tools

The server provides the following tools for Claude to use:

1. create_task: Create a new task in Todoist

   • Required: content (title of the task)
   • Optional:
     • description,
     • due_date,
     • priority,
     • project_id,
     • section_id,
     • labels

2. get_tasks: Get a list of tasks and Ids from Todoist with various filters

   • Optional:
     • project_id,
     • project_name,
     • task_name,
     • priority,
     • labels,
     • is_overdue,
     • limit

3. update_task: Update an existing task by searching for it by name

   • Required: task_id
   • Optional:
     • content,
     • description,
     • labels,
     • priority,
     • due_date (YYYY-MM-DD),
     • deadline_date (YYYY-MM-DD)

4. delete_task: Delete a task by searching for it by name

   • Required: task_id

5. complete_task: Mark a task as complete by searching for it by name

   • Required: task_id

Example Interactions

Here are some examples of how Claude can interact with Todoist through this MCP server:

• “Add a task to buy groceries”
• “Show me all my urgent tasks”
• “What tasks are due today?”
• “Mark the laundry task as done”
• “Change the priority of my dentist appointment to urgent”

Security Considerations

• The server securely handles your Todoist API token through environment variables
• Never share your .env file or expose your API token
• The server runs locally and communicates only with the Todoist API

License

MIT License

Acknowledgements

• Todoist API Python Client
• Model Context Protocol