AI导哈

任务管理协议服务器

一个为Todoist设计的模型上下文协议（MCP）服务器，通过自然对话使AI助手能够管理任务、项目、标签、部分和评论。

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

使用说明

Todoist MCP服务器

Todoist的全面模型上下文协议（MCP）服务器，使AI助手能够通过自然对话管理任务、项目、标签、部分和评论。

特性

Todoist MCP服务器提供完整的任务管理功能：

📁 项目管理

  • 列出项目 -查看所有具有层次结构、颜色和元数据的项目
  • 创建项目 -添加具有自定义选项的新项目
  • 更新项目 -修改项目属性，如名称、颜色和视图样式

✅ 任务操作

  • 列出任务 -使用筛选器查看任务（按项目、标签或Todoist筛选器）
  • 创建任务 -添加对属性具有完全控制权的任务
  • 快速添加任务 -使用自然语言创建任务
  • 更新任务 -修改任务内容、截止日期、优先级和标签
  • 完成任务 -将任务标记为已完成（自动处理重复任务）

📑 组织

  • 章节 -列出并创建部分以组织项目中的任务
  • 标签 -管理个人标签以进行任务分类
  • 评论 -添加和查看任务和项目的评论

安装

先决条件

  • Python 3.9或更高版本
  • 具有API访问权限的Todoist帐户
  • 您的Todoist API令牌（可在“设置”中找到→ 集成→ 开发商）

设置

  1. 安装MCP Python SDK和依赖项：
pip install mcp httpx pydantic
  1. 保存服务器文件：

保存 todoist_mcp.py 到您系统上的某个位置（例如。， ~/mcp-servers/todoist/)

  1. 使其可执行：
chmod +x todoist_mcp.py

配置

适用于克劳德桌面

将以下内容添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "todoist": {
      "command": "python",
      "args": ["/path/to/todoist_mcp.py"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

替换：

  • /path/to/todoist_mcp.py 带有服务器文件的实际路径
  • your_api_token_here 使用Todoist API代币

获取您的Todoist API代币

  1. 登录Todoist
  2. 转到“设置”→ 集成→ 开发者
  3. 复制您的API令牌
  4. 保持安全-此令牌提供对Todoist帐户的完全访问权限

使用示例

配置后，您可以通过自然语言与Todoist交互：

项目管理

  • “显示我的所有Todoist项目”
  • “创建一个名为‘Q1目标’的红色新项目”
  • “让我的工作项目成为最爱”
  • “将我的个人项目更改为板视图”

任务管理

  • “我今天有什么任务要交？”
  • “在我明天到期的工作项目中创建一个任务“审查季度报告”，具有高优先级”
  • “添加任务‘下周一下午2点致电牙医#Health p2’”（使用快速添加）
  • “将任务123456标记为已完成”
  • “将我的‘买牛奶’任务更新为明天到期”
  • “显示所有带有“紧急”标签的任务”
  • “列出我的工作项目中的任务”

组织

  • “在我的工作项目中创建一个名为“进行中”的部分”
  • “显示我的所有标签”
  • “创建一个名为“等待”的蓝色新标签”
  • 在任务789012中添加注释“已开始处理此问题”

自然语言快速添加

快速添加功能理解：

  • 项目: @ProjectName 或 #ProjectName
  • 标签: @LabelName
  • 优先级: p1, p2, p3, p4 或 !, !!, !!!
  • 到期日: today, tomorrow, next Monday, Jan 15等等。

示例：

  • “明天下午3点开会#工作p2”
  • “今天买杂货@购物”
  • “每周五审查文件#工作”

可用工具

工具 说明
todoist_list_projects 列出所有具有层次结构和元数据的项目
todoist_create_project 创建新项目
todoist_update_project 更新项目属性
todoist_list_tasks 列出带有可选筛选器的任务
todoist_create_task 创建具有完全控制权的任务
todoist_quick_add_task 使用自然语言添加任务
todoist_update_task 更新任务属性
todoist_complete_task 将任务标记为已完成
todoist_list_sections 列出项目部分
todoist_create_section 创建新节
todoist_list_labels 列出个人标签
todoist_create_label 创建新标签
todoist_get_comments 获取任务/项目的评论
todoist_add_comment 添加评论

响应格式

大多数工具支持两种响应格式：

  • 标记语言 （默认）：带有表情符号和结构的人类可读格式化文本
  • JSON：具有完整数据的机器可读格式

服务器根据上下文自动使用适当的格式。

速率限制

Todoist API有以下限制：

  • 每位用户每15分钟最多1000个请求
  • 最大请求正文大小为1 MB
  • 每个请求处理超时15秒

当超过限制时，服务器会提供明确的错误消息。

错误处理

服务器提供清晰、可操作的错误消息：

  • API令牌错误与设置指南无效
  • 带有等待建议的速率限制通知
  • 找不到带有ID验证提示的资源错误
  • 带有重试建议的网络超时处理

安全说明

  • 安全地存储您的API令牌-永远不要将其提交到版本控制
  • API令牌提供对Todoist帐户的完全访问
  • 使用环境变量进行令牌存储
  • 考虑使用单独的Todoist帐户进行测试

故障排除

常见问题

  1. “无效的API令牌”错误：

    • 在Todoist设置中验证您的令牌→ 集成→ 开发者
    • 确保在配置中正确设置了令牌

  2. “找不到资源”错误：

    • 检查项目/任务ID是否正确
    • ID现在是Todoist API v2中的字符串

  3. 速率限制错误：

    • 等待15分钟再提出更多请求
    • 在可能的情况下考虑批处理操作

  4. 连接超时：

    • 检查您的互联网连接
    • Todoist API可能暂时不可用

调试模式

要查看详细的错误消息，请直接运行服务器：

TODOIST_API_TOKEN=your_token python todoist_mcp.py

发展

添加新功能

该服务器使用FastMCP构建，并遵循MCP最佳实践：

  • 用于输入验证的Pydantic模型
  • 全面的错误处理
  • 支持Markdown和JSON响应
  • 大响应的字符限制处理

编码结构

  • Pydantic模型：所有操作的输入验证
  • 实用函数：共享API请求、错误处理、格式化
  • 工具定义：每个工具都有全面的文档字符串
  • 响应格式：Markdown和JSON输出选项

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题或疑问：

  1. 查看Todoist API文档：https://developer.todoist.com/rest/v2/
  2. 审查MCP文件：https://modelcontextprotocol.io/
  3. 在项目存储库中提交问题

更新日志

1.0.0版本（首次发布）

  • 完整的项目管理（列表、创建、更新）
  • 全任务操作（CRUD、完成、快速添加）
  • 区段和标签管理
  • 评论系统支持
  • 自然语言任务创建
  • 全面的错误处理
  • 支持所有Todoist过滤器
  • Markdown和JSON响应格式

相关 MCP