AI导哈

Todoist集成服务

一个与Todoist集成的模型上下文协议（MCP）服务器，允许语言模型与Todoist的任务和项目进行交互。

  • by stevengonsalvez
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 stevengonsalvez/mcp-todoist

使用说明

MCP Todoist集成

该项目提供了 模型上下文协议（MCP） 与Todoist集成的服务器，允许语言模型与Todoist任务和项目交互。

特性

  • 完成Todoist API集成
  • 创建、阅读、更新和删除任务、项目、节、标签和注释
  • 访问项目合作者
  • 按各种条件筛选任务
  • 用于语言模型的文档化工具和资源

需求

  • Python 3.10或更高版本
  • 使用API令牌的Todoist帐户
  • MCP兼容客户端（如克劳德桌面）

使用Claude Desktop

要将此MCP服务器与Claude Desktop一起使用，您有两个选项：

选项1：使用uvx（推荐）

  1. 使用uvx安装软件包：

    uvx install mcp-todoist

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

    • 打开克劳德桌面
    • 前往“设置”>“高级”
    • 在“MCP服务器配置”下，向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配置中：

    • 打开克劳德桌面
    • 前往“设置”>“高级”
    • 在“MCP服务器配置”下，向JSON配置中添加：
      "mcpServers": {
  "todoist": {
    "command": "python",
    "args": ["/full/path/to/mcp-todoist/main.py"],
    "env": {
      "TODOIST_API_TOKEN": "your_todoist_api_token_here"
    }
  }
}

选项3：使用紫外线

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桌面：

    "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. 前往“设置”>“集成”
  3. 从“API令牌”部分复制API令牌

安装

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

  1. 克隆此存储库：

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

  2. 安装依赖项：

    pip install -r requirements.txt

  3. 创建一个 .env 使用Todoist API令牌文件：

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

使用MCP开发工具运行

对于测试和开发，请使用MCP开发工具：

mcp run main.py

这将启动MCP服务器，允许您以交互方式对其进行测试。

要使用MCP检查器进行视觉交互，请执行以下操作：

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. 分叉存储库
  2. 进行更改
  3. 测试用 mcp run main.py 或 mcp dev main.py
  4. 提交拉取请求

利用紫外线进行开发

此项目支持使用 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挂钩

此项目使用预提交挂钩来确保代码质量和一致性：

  1. 安装开发依赖项：

    pip install -e ".[dev]"

  2. 安装git挂钩：

    pre-commit install

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

    • 黑色用于代码格式化
    • isort用于导入排序
    • 8号棉绒片
    • 各种文件检查（尾随空格、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存储库→ 行动→ “构建和发布”工作流
    • 点击“运行工作流”
    • 为测试PyPI选择“test”或为生产PyPI选择”prod“

许可证

该项目根据 MIT许可证。请参阅 许可证 文件以获取详细信息。

相关 MCP