todoist mcp python

Local 2025-09-01 00:17:51 0
Developer Tools @Johnxjp/todoist-mcp-python

A Model Context Profile server that enables Claude to interact with Todoist, allowing users to create, retrieve, update, and manage tasks through natural language commands.

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
  2. Required: content (title of the task)

  3. Optional:

    • description,
    • due_date,
    • priority,
    • project_id,
    • section_id,
    • labels

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

  5. Optional:

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

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

  7. Required: task_id

  8. Optional:

    • content,
    • description,
    • labels,
    • priority,
    • due_date (YYYY-MM-DD),
    • deadline_date (YYYY-MM-DD)

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

  10. Required: task_id

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

  12. 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