MCP-Todoist Integration

MCP-Todoist 集成

本项目提供一个 Model Context Protocol（MCP） 服务，可与 Todoist 集成，让大模型能够与 Todoist 任务和项目交互。

功能

• 完整集成 Todoist API
• 创建、读取、更新和删除任务、项目、分区、标签和评论
• 访问项目协作者
• 按各种条件筛选任务
• 提供完善的工具和资源文档，供大模型使用

要求

• Python 3.10 或更高版本
• 拥有 API 令牌的 Todoist 账户
• 兼容 MCP 的客户端（如 Claude Desktop）

在 Claude Desktop 中使用

要在 Claude Desktop 中使用此 MCP 服务，有两种选择：

选项 1：使用 uvx（推荐）

1. 使用 uvx 安装软件包：

   uvx install mcp-todoist
   

2. 将服务添加到 Claude Desktop 的 MCP 配置中：

   • 打开 Claude Desktop
   • 前往 Settings > Advanced
   • 在“MCP Servers Configuration”下，将以下内容添加到 JSON 配置中：

     "mcpServers": {
       "todoist": {
         "command": "uvx",
         "args": ["mcp-todoist"],
         "env": {
           "TODOIST_API_TOKEN": "your_todoist_api_token_here"
         }
       }
     }
     

选项 2：使用克隆的仓库

1. 克隆仓库并以开发模式安装软件包：

   git clone https://github.com/your-username/mcp-todoist.git
   cd mcp-todoist
   pip install -e .
   

2. 将服务添加到 Claude Desktop 的 MCP 配置中：

   • 打开 Claude Desktop
   • 前往 Settings > Advanced
   • 在“MCP Servers Configuration”下，将以下内容添加到 JSON 配置中：

     "mcpServers": {
       "todoist": {
         "command": "python",
         "args": ["/full/path/to/mcp-todoist/main.py"],
         "env": {
           "TODOIST_API_TOKEN": "your_todoist_api_token_here"
         }
       }
     }
     

选项 3：使用 uv

uv 是一款快速的 Python 软件包安装器和解析器。要在本项目中使用它：

1. 首先确保已安装 uv：

   # Install uv (if you haven't already)
   brew install uv  # On macOS with Homebrew
   pipx install uv  # Or use pipx
   

2. 克隆仓库：

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

3. 创建并维护锁定文件：

   # Create/update the lock file (do this when dependencies change)
   uv pip sync requirements.txt
   

4. 使用 uv 运行 MCP 服务：

   uv run mcp dev main.py
   

5. 配置 Claude Desktop：

   "mcpServers": {
     "todoist": {
       "command": "uv",
       "args": ["run", "mcp", "dev", "/full/path/to/mcp-todoist/main.py"],
       "env": {
         "TODOIST_API_TOKEN": "your_todoist_api_token_here"
       }
     }
   }
   

6. 保存配置并重启 Claude Desktop

7. 现在，你可以在 Claude 对话中让 Claude 使用 Todoist，以访问 Todoist MCP 服务

获取 Todoist API 令牌

获取 Todoist API 令牌的步骤：

1. 登录 Todoist 账户
2. 前往 Settings > Integrations
3. 从“API token”部分复制 API 令牌

安装

如果要从源代码安装软件包：

1. 克隆此仓库：

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

2. 安装依赖项：

   pip install -r requirements.txt
   

3. 创建一个包含 Todoist API 令牌的 .env 文件：

   cp .env.example .env
   # Edit .env file to add your Todoist API token
   

使用 MCP Dev Tools 运行

如需测试和开发，请使用 MCP 开发工具：

mcp run main.py

这将启动 MCP 服务，供你交互式测试。

如需通过 MCP Inspector 进行可视化交互，请运行：

mcp dev main.py

可用工具

以下 Todoist 工具可用：

任务管理

• create_task - 创建新任务，可设置标题、截止日期、项目等。
• get_tasks - 根据筛选条件获取任务
• get_task - 按 ID 获取指定任务
• update_task - 更新现有任务
• complete_task - 将任务标记为已完成
• uncomplete_task - 将已完成的任务标记为未完成
• delete_task - 删除任务

项目管理

• get_projects - 获取所有项目
• get_project - 按 ID 获取指定项目
• add_project - 创建新项目
• update_project - 更新现有项目
• delete_project - 删除项目
• archive_project - 归档项目
• unarchive_project - 取消归档项目

分区管理

• get_sections - 获取项目中的所有分区
• get_section - 按 ID 获取指定分区
• add_section - 创建新分区
• update_section - 更新现有分区
• delete_section - 删除分区

标签管理

• get_labels - 获取所有标签
• get_label - 按 ID 获取特定标签
• add_label - 创建新标签
• update_label - 更新现有标签
• delete_label - 删除标签

评论管理

• get_comments - 获取任务或项目的评论
• get_comment - 按 ID 获取特定评论
• add_comment - 为任务或项目添加评论
• update_comment - 更新现有评论
• delete_comment - 删除评论

协作

• get_collaborators - 获取项目的协作者

可用资源

以下 Todoist 资源可用：

• todoist://tasks - 所有任务
• todoist://tasks/project/{project_id} - 特定项目中的任务
• todoist://tasks/section/{section_id} - 特定分区中的任务
• todoist://tasks/label/{label} - 带有特定标签的任务
• todoist://projects - 所有项目
• todoist://sections/{project_id} - 特定项目中的分区
• todoist://labels - 所有标签

示例

创建任务

Please create a new task in Todoist called "Buy groceries" due tomorrow.

获取项目中的任务

Show me all tasks in my "Work" project.

完成任务

Mark the "Buy groceries" task as complete.

为任务添加评论

Add a comment to the task with ID "12345678" saying "Don't forget milk and eggs".

创建包含分区的新项目

Create a new project called "Home Renovation" and add sections for "Kitchen", "Bathroom", and "Living Room".

开发

如需为项目做出贡献或根据自身需求修改项目：

1. Fork 此仓库
2. 进行修改
3. 使用 mcp run main.py 或 mcp dev main.py 测试
4. 提交拉取请求

使用 uv 进行开发

此项目支持使用 uv 来更快地管理依赖项和运行程序：

1. 依赖项发生变化时，创建/更新锁文件：

   uv pip sync requirements.txt
   

2. 使用 uv 运行应用程序：

   uv run mcp dev main.py
   

3. 如果遇到锁文件问题，可以通过以下方式排查：

   # Remove the lock file and regenerate it
   rm uv.lock
   uv pip sync requirements.txt
   
   # Or run without using the lock file (temporary solution)
   UV_LOCK=0 uv run mcp dev main.py
   

Git 钩子

此项目使用 pre-commit 钩子来确保代码质量和一致性：

1. 安装开发依赖项：

   pip install -e ".[dev]"
   

2. 安装 git 钩子：

   pre-commit install
   

3. 现在，每次提交时都会运行这些钩子：

   • Black，用于代码格式化
   • isort，用于导入排序
   • flake8，用于代码检查
   • 各种文件检查（行尾空格、YAML 验证等）

如果任何钩子运行失败，提交将被中止。修复问题后重试。

你也可以手动对所有文件运行这些钩子：

pre-commit run --all-files

发布到 PyPI

此项目使用 setuptools_scm 根据 git 标签自动确定版本：

1. 确保所有测试都在本地通过：

   pip install -e ".[dev]"
   flake8 . --exclude=.venv,venv,env
   black --check .
   isort --check-only --profile black .
   pytest
   

2. 使用语义化版本控制创建新版本（不带「v」前缀）：

   # For a new version (e.g., 0.1.0)
   git tag 0.1.0
   git push origin 0.1.0
   

3. GitHub Actions 工作流将自动：

   • 运行测试
   • 根据 PR 和提交生成变更日志
   • 创建包含变更日志的 GitHub 版本发布
   • 构建并将软件包发布到 PyPI

4. 手动发布（如有需要）：

   pip install build twine
   python -m build
   twine check dist/*
   twine upload --repository-url https://test.pypi.org/legacy/ dist/*  # Test first
   twine upload dist/*  # Then to production PyPI
   

5. 备选方案：手动触发工作流：

   • 前往 GitHub 仓库 → Actions →「Build and Publish」工作流
   • 点击「Run workflow」
   • 选择「test」以发布到 Test PyPI，或选择「prod」以发布到正式 PyPI

许可证

此项目基于 MIT License 授权。详情请参阅 LICENSE 文件。