# Todoist Mcp Server

> Open-source Python MCP server for Todoist. Use to create & provide structured tasks for Cursor, or to automatically create tasks based on your Gmail/Drive with Claude Desktop.

- **Type:** MCP server
- **Install:** `agentstack add mcp-koji0701-todoist-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [koji0701](https://agentstack.voostack.com/s/koji0701)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [koji0701](https://github.com/koji0701)
- **Source:** https://github.com/koji0701/todoist-mcp-server

## Install

```sh
agentstack add mcp-koji0701-todoist-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Todoist MCP Server

[](https://smithery.ai/server/@koji0701/todoist-mcp-server)
[](https://www.python.org/downloads/)
[](LICENSE) 

# Todoist MCP Server

A [Model Context Protocol (MCP) server](https://modelcontextprotocol.io/introduction) for interacting with Todoist. This server allows you to manage your Todoist tasks using natural language commands through an MCP-compatible client. This server is built using `fastmcp` and the `todoist-api-python` library.
## About The Project

You can run this server locally, and an MCP-compatible client (like Claude desktop) can then call its tools to perform actions in your Todoist. Check the project out on [Smithery](https://smithery.ai/server/@koji0701/todoist-mcp-server).

Key functionalities include:
- Creating, reading, updating, and deleting tasks, projects, sections, labels, and comments.
- Fetching data with filters and pagination.
- Support for both `stdio` and `SSE` (Server-Sent Events) transport for MCP communication.

## Recommended Use Cases
- I primarily recommend using this in Claude Desktop or any other LLM that supports MCP integration. Here's how I use it:
    - Combine this with Google Calendar (or any other calendar) MCP to automatically timeblock your tasks based on times you are available, their deadlines, and priority levels. Also, you can automatically break down larger tasks into subtasks and schedule them over several days. 
    - Combine this with an email MCP to generate + schedule tasks in Todoist. Especially useful for Canvas email notifications, and automatically scheduling homework.
    - Vibe-coding? Vibe-plan a sectioned, project plan with actionable, assigned tasks and descriptions that you can share with group members.

## Prerequisites

- **Todoist Account:** A valid Todoist account.
- **Todoist API Token:** You can get your API token from your Todoist App: Settings -> Integrations -> Developer API Token.
- **Python:** Version 3.12 or higher.
- **Package Manager:** Either `uv` (recommended for speed) or `pip` with `venv`/`conda`

## Installation

The (highly) recommended way to install and use this MCP server is with Smithery. Smithery is a command-line tool that helps you discover, install, and manage MCP servers. 

### Using Smithery CLI

1.  **Install Smithery CLI (if you haven't already):**
    You can install the Smithery CLI using npm:
    ```bash
    npm install -g @smithery/cli
    ```
    Or use it directly with `npx`:
    ```bash
    npx -y @smithery/cli --help
    ```

2.  **Install the Todoist MCP Server:**
    Use the Smithery CLI to install this server for your preferred MCP client. Replace `` with the client you are using (e.g., `claude`, `cursor`, `windsurf`).
    ```bash
    npx -y @smithery/cli install @koji0701/todoist-mcp-server --client 
    ```
    For example, to install it for Claude Desktop: 
    ```bash
    npx -y @smithery/cli install @koji0701/todoist-mcp-server --client claude
    ```
    Or for Cursor: 
    ```bash
    npx -y @smithery/cli install @koji0701/todoist-mcp-server --client cursor
    ```
    Smithery will attempt to automatically configure the server with your chosen client. 

## Configuration

### Todoist API Token

To allow this server to interact with your Todoist account, you need to provide a Todoist API token.

1.  Log in to your Todoist account.
2.  Go to **Settings** > **Integrations**.
3.  Under the "Developer" section, you will find your API token.
4.  Copy this token.

The Smithery installation process might prompt you for this token, or you may need to set it as an environment variable. The typical environment variable name is `TODOIST_API_KEY` or `TODOIST_TOKEN`. Please check the specific instructions provided by Smithery during installation or the requirements of your MCP client. 

## Usage

Once installed and configured, your MCP client (e.g., Claude Desktop, Cursor) will be able to list and utilize the tools provided by this server. You can then interact with your Todoist tasks using natural language prompts within your client.

Example (general idea, actual phrasing depends on the client and LLM):
*   "Create a new task in Todoist: Buy milk, due tomorrow."
*   "What are my Todoist tasks for today?"
*   "Mark 'Finish report' as complete in Todoist."

Refer to the documentation of your specific MCP client for more details on how to invoke tools.

## Tools

This server will expose tools for common Todoist operations, such as:

*   Creating tasks
*   Getting (listing/filtering) tasks
*   Updating tasks
*   Completing tasks
*   Deleting tasks

You can find the specific list of tools and their parameters by:
*   Checking the server's page on Smithery: [https://smithery.ai/server/%40koji0701%2Ftodoist-mcp-server/tools](https://smithery.ai/server/%40koji0701%2Ftodoist-mcp-server/tools)
*   Using a command within your MCP client to list available tools from this server (if supported by the client).

## Development (Optional, runs it locally)

If you want to contribute to this server or run it manually:

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/koji0701/todoist-mcp-server.git
    cd todoist-mcp-server
    ```
2.  **Install dependencies:**
    (Assuming Python is installed. Choose one of the following methods based on your preferred package/environment manager.)

    ```bash
    # Using uv
    uv pip install -r requirements.txt
    ```
    ```bash
    # Or using Conda
    # 1. Create and activate a new conda environment
    conda create -n todoist_mcp_env python=3.12 
    conda activate todoist_mcp_env

    # 2. Install dependencies using pip within the conda environment
    pip install -r requirements.txt
    ```
    ```bash
    # Or using pip with venv
    python -m venv .venv
    source .venv/bin/activate  # On Windows, use: .venv\Scripts\activate
    pip install -r requirements.txt
    ```


3.  **Set environment variables:**
    Create a `.env` file in the project root directory (`todoist-mcp-server/.env`):
    ```env
    TODOIST_API_TOKEN="YOUR_TODOIST_API_TOKEN"

    # Optional: For SSE transport (defaults to stdio if not set)
    # TRANSPORT="sse"
    # MCP_HOST="127.0.0.1"  # Default host for SSE
    # MCP_PORT="8080"       # Default port for SSE
    ```
    Replace `"YOUR_TODOIST_API_TOKEN"` with your actual Todoist API token.
4.  **Run the server:**
    *   **If using `uv`:**
        ```bash
        uv run server.py
        ```
        (`uv run` executes the command within the project's managed environment.)

    *   **If using `pip` with `venv` or `conda` (ensure the environment is activated):**
        ```bash
        python server.py
        ```

This will typically start the server locally. You would then need to configure your MCP client to connect to this local instance if not using Smithery for a production/deployed setup.

## Usage (if running locally)

1.  **Run the server:**
    Navigate to the project directory.

    *   **If using `uv`:**
        ```bash
        uv run server.py
        ```
        (`uv run` executes the command within the project's managed environment.)

    *   **If using `pip` with `venv` or `conda` (ensure the environment is activated):**
        ```bash
        python server.py
        ```
    You should see log messages indicating the server has started, e.g., `Starting Todoist MCP server with stdio transport...` or similar if SSE is configured.

2.  **Transport Modes:**
    The server can communicate with MCP clients using two transport modes, configured via the `TRANSPORT` environment variable (e.g., in your `.env` file or directly in the execution environment like in the Claude Desktop example).

    *   **`stdio` (default):** The server communicates over standard input/output.
        *   **When to use:** This mode is ideal for local MCP clients that manage the server as a subprocess. For example, **Claude Desktop's custom tools feature typically relies on `stdio` communication.** If `TRANSPORT` is not set, it defaults to `stdio`.
    *   **`SSE` (Server-Sent Events):** The server uses Server-Sent Events over HTTP.
        *   **When to use:** This mode is suitable for network-based MCP clients or when the server needs to be accessible over a network.
        *   To use SSE, set `TRANSPORT=sse` in your `.env` file.
        *   The host can be configured with `MCP_HOST` (default: `127.0.0.1`).
        *   The port can be configured with `MCP_PORT` (default: `8080`).

3.  **Interacting with the server (general):**
    This server is designed to be used by an MCP client. For testing, if you have the `mcp` CLI tool installed:

    **Example using `mcp` CLI with a server running in `SSE` mode (on default http://127.0.0.1:8080):**
    ```bash
    # Ensure TRANSPORT=sse is set in your .env and the server is running (e.g., via 'uv run server.py')
    # List all projects
    mcp client call --uri http://127.0.0.1:8080/mcp todoist.get_projects

    # Add a new task
    mcp client call --uri http://127.0.0.1:8080/mcp todoist.add_task --content "Buy groceries" --due_string "tomorrow"
    ```

### Using with Claude Desktop (if running locally)

Claude Desktop's custom tools feature allows you to integrate local MCP servers like this one.

1.  **Ensure Prerequisites are Met:**
    *   You have installed the server following one of the methods above.
    *   Your `TODOIST_API_TOKEN` is accessible to the server (via `.env` and directly in the Claude Desktop tool configuration as shown below).

2.  **Configure Custom Tool in Claude Desktop:**
    *   Open Claude Desktop and navigate to the custom tools configuration.
    *   Add a new tool, using a configuration structure similar to the example below.
    *   **Important:** You **must** adjust the paths in the `command` and `args` (specifically the `--directory` path) to match your local setup. Also, the `command` itself (e.g., `/opt/anaconda3/envs/mcp-py312/bin/uv`) should point to your specific `uv` executable or the Python executable from your chosen virtual environment if you are not using `uv` as the direct command.

    **Example JSON Configuration for Claude Desktop:**
    ```json
    {
        "mcpServers": {
            "todoist": {
                "command": "/opt/anaconda3/envs/mcp-py312/bin/uv", // ", // ` with your actual token.
        *   `PYTHONUNBUFFERED=1`: Recommended for `stdio` tools to ensure smooth communication.
        *   `TRANSPORT="stdio"`: Explicitly sets the transport mode for Claude Desktop.
    *   **Tool Name/Namespace:** Claude Desktop will discover tools under the `todoist` namespace (e.g., `todoist.add_task`).

3.  **Using the Tools in Claude:**
    Once configured, you should be able to invoke the Todoist tools from your Claude conversations. For example:
    `"Claude, can you add a task to my Todoist to 'Review project proposal' for tomorrow?"`
    Claude should then identify the need to use the `todoist.add_task` tool.

## Configuration (via .env file)

If not configuring environment variables directly in the MCP client (like the Claude Desktop example), the server can be configured using a `.env` file in the project root:

-   `TODOIST_API_TOKEN` (Required): Your API token for accessing Todoist.
-   `TRANSPORT` (Optional): Specifies the communication transport.
    -   `stdio` (default): Uses standard input/output.
    -   `sse`: Uses Server-Sent Events over HTTP.
-   `MCP_HOST` (Optional, for SSE): The host address for the SSE server to bind to. Defaults to `127.0.0.1`.
-   `MCP_PORT` (Optional, for SSE): The port for the SSE server to listen on. Defaults to `8080`.

## Available MCP Tools

The server exposes the following tools under the `todoist` namespace:

### Tasks
*   `add_task`: Create a new task.
*   `get_task`: Get a specific task by its ID.
*   `get_tasks`: Get active tasks, optionally filtered.
*   `filter_tasks`: Get active tasks matching a filter query.
*   `add_task_quick`: Create a new task using Todoist's Quick Add syntax.
*   `update_task`: Update an existing task.
*   `complete_task`: Complete a task (maps to `close_task`).
*   `uncomplete_task`: Uncomplete a task (maps to `reopen_task`).
*   `move_task`: Move a task to a different project or section (via `update_task`).
*   `delete_task`: Delete a task.
*   `get_completed_tasks_by_due_date`: Get completed tasks within a due date range.
*   `get_completed_tasks_by_completion_date`: Get completed tasks within a completion date range.

### Projects
*   `add_project`: Create a new project.
*   `get_project`: Get a project by its ID.
*   `get_projects`: Get all active projects.
*   `update_project`: Update an existing project.
*   `archive_project`: Archive a project.
*   `unarchive_project`: Unarchive a project.
*   `delete_project`: Delete a project.
*   `get_collaborators`: Get collaborators in a shared project.

### Sections
*   `add_section`: Create a new section within a project.
*   `get_section`: Get a specific section by its ID.
*   `get_sections`: Get all active sections, optionally filtered by project.
*   `update_section`: Update an existing section's name.
*   `delete_section`: Delete a section.

### Labels
*   `add_label`: Create a new personal label.
*   `get_label`: Get a specific personal label by its ID.
*   `get_labels`: Get all personal labels.
*   `update_label`: Update a personal label.
*   `delete_label`: Delete a personal label.
*   `get_shared_labels`: Get shared labels.
*   `rename_shared_label`: Rename a shared label (finds by name, updates by ID).
*   `remove_shared_label`: Remove a shared label (finds by name, deletes by ID).

### Comments
*   `add_comment`: Create a new comment on a task or project.
*   `get_comment`: Get a specific comment by its ID.
*   `get_comments`: Get comments for a task or project.
*   `update_comment`: Update an existing comment's content.
*   `delete_comment`: Delete a comment.

Refer to the `server.py` file for detailed parameters of each tool.

## Project Structure

-   `server.py`: Contains the main application logic, MCP tool definitions, and server execution.
-   `utils.py`: Utility functions, primarily for initializing the Todoist API client.
-   `main.py`: A minimal entry point (currently `server.py` is the primary executable script).
-   `pyproject.toml`: Defines project metadata, dependencies, and build system configuration.
-   `uv.lock`: Lock file for `uv` package manager, ensuring reproducible builds.
-   `.gitignore`: Specifies files and directories to be ignored by Git.
-   `.python-version`: Specifies the Python version (used by tools like `pyenv`).
-   `README.md`: This file.

## Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue for bugs, feature requests, or improvements. Also, feel free to use this as a template for developing your own MCP server. 

1.  Fork the Project
2.  Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3.  Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4.  Push to the Branch (`git push origin feature/AmazingFeature`)
5.  Open a Pull Request

## License

Distributed under the MIT License. See `LICENSE` for more information.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [koji0701](https://github.com/koji0701)
- **Source:** [koji0701/todoist-mcp-server](https://github.com/koji0701/todoist-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-koji0701-todoist-mcp-server
- Seller: https://agentstack.voostack.com/s/koji0701
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.