MCP Todoist

🚀 MCP-Todoist

MCP-Todoist is an application designed to interact with the Todoist service. With this project, you can manage your tasks and projects directly in the terminal or other environments that support MCP (Multi-Command Processor).

🚀 Quick Start

Before using MCP-Todoist, you need to complete the installation and configuration. Please refer to the following sections for detailed steps.

✨ Features

• Manage Todoist tasks and projects directly in the terminal or MCP-supported environments.
• Support for creating, querying, updating task status, and adding notes to tasks.

📦 Installation

To install MCP-Todoist, follow these steps:

1. Clone this repository to your local machine:

   git clone https://github.com/yourusername/mcp-todoist.git
   cd mcp-todoist
   

2. Install using the Python package manager pip:

   pip install .
   

3. After installation, you can test if MCP-Todoist is working properly by running the following command:

   mcp --help
   

📚 Documentation

Project Configuration

Before using MCP-Todoist, please complete the following configuration:

1. Get a Todoist API Key: Visit the Todoist website, log in to your account, and then go to the settings page to obtain the API access token.

2. Create a Configuration File: Create a file named config.json in the project root directory and add the following content:

   {
     "todoist": {
       "token": "your_api_token_here"
     }
   }
   

💻 Usage Examples

Basic Usage

1. Create a New Task

To create a new Todoist task, run the following command:

mcp todoist create-task --title "Task Title" [--due-date YYYY-MM-DD]

• --title: Required parameter, specifying the title of the task.
• --due-date: Optional parameter, specifying the due date of the task.

For example:

mcp todoist create-task --title "Buy groceries" --due-date 2023-10-25

2. Query Tasks

To query tasks in Todoist, use the following commands:

Query by Project

mcp todoist list-tasks --project "Project Name"

For example:

mcp todoist list-tasks --project Work

Query by Label

mcp todoist list-tasks --label "Label Name"

For example:

mcp todoist list-tasks --label Important

3. Update Task Status

To update the completion status of a task, run the following commands:

Mark a Task as Completed

mcp todoist complete-task --task-id ID

For example:

mcp todoist complete-task --task-id 12345678

Mark a Task as Incomplete

mcp todoist uncomplete-task --task-id ID

For example:

mcp todoist uncomplete-task --task-id 12345678

4. Add a Note to a Task

To add a note to a task, use the following command:

mcp todoist add-note --task-id ID --content "Your note content"

For example:

mcp todoist add-note --task-id 12345678 --content "Remember to bring an umbrella"

Development Guide

Install the Development Environment

To contribute to the development of MCP-Todoist, please configure as follows:

1. Clone the repository:

   git clone https://github.com/yourusername/mcp-todoist.git
   cd mcp-todoist
   

2. Create a virtual environment (recommended):

   python -m venv env
   source env/bin/activate  # Use `env\Scripts\activate` on Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   

Contribution Guidelines

If you wish to contribute to MCP-Todoist, please follow these steps:

1. Report Issues: Report any issues or improvement suggestions you encounter on the GitHub Issues page.

2. Create Feature Requests: If a feature is not yet implemented, submit it on the Feature Requests page.

3. Submit Code Changes:

   • Create a branch for your changes:

     git checkout -b feature/new-feature-name
     

   • Commit your changes and push them to the remote repository:

     git add .
     git commit -m "Describe the changes you've made"
     git push origin feature/new-feature-name
     

   • Create a Pull Request to the main branch.

Use Git Hooks

To ensure code quality, it is recommended to configure the following Git Hooks in the project:

1. Pre-Commit Hook: Add the following content to the .git/hooks/pre-commit file in the project root directory to automatically check the code format:

   #!/bin/bash
   flake8 --check .
   black --check .
   

2. Branch Naming Convention: Please follow the following branch naming convention:

   • New features: feature/<Feature Name>
   • Bug fixes: bugfix/<Issue ID>
   • Hotfixes: hotfix/<Version Number>

Use CI/CD

The project has integrated GitHub Actions for automated testing and building. After each code submission, the CI/CD process will automatically perform the following operations:

1. Run Unit Tests:

   pytest tests/
   

2. Check Code Format:

   black --check .
   flake8 .
   

3. Build and Publish the Package (only on the main branch).

Resource Links

• Todoist Official Documentation
• MCP-Todoist Project Repository
• Project Contributors List

Troubleshooting

Frequently Asked Questions

1. How to get a Todoist API Token?

   • Log in to your Todoist account, go to the settings page, find the API section, and click the "Generate New Token" button.

2. What if I can't connect to the Todoist service?

   • Make sure your API Token is correct.
   • Check your network connection.
   • Try performing the same operation on the Todoist website to confirm if the problem still exists.

3. How to update MCP-Todoist to the latest version?

   pip install --upgrade mcp-todoist
   

Development Resources

Third-Party Dependencies

• click: Used for command-line interface development.
• todoist-api-python: Used to interact with the Todoist API.

Contributors

Thank the following people for their contributions to MCP-Todoist:

• Your Name
• Contributor 1
• Contributor 2

📄 License

The MCP-Todoist project follows the MIT License.