Name: Todoist MCP 服务器
Author: mariomosca

使用说明

🚀 高级Todoist MCP服务器

一个复杂的模型上下文协议（MCP）服务器，用于Todoist与Claude等人工智能助手的无缝集成

这个基于TypeScript的MCP服务器通过模型上下文协议实现了与Todoist的高级交互，使Claude和其他LLM能够以前所未有的深度和灵活性智能地访问、分析和操纵您的Todoist项目和任务。

🌐 公文包项目：此服务器展示了先进的MCP开发专业知识、TypeScript架构和人工智能工作流优化 mariomosca.com.

✨ 独特功能和差异化因素

🧠 智能资源发现

分层项目导航：自动检测和映射项目层次结构及其子项目
今天的任务优化：用于当前任务管理的专用资源
动态资源生成：基于您的实际Todoist数据的实时资源发现
上下文感知描述：理解项目关系的智能描述

🔄 高级状态管理

德尔塔探测系统：跟踪自上次交互以来的更改（独特功能！）
分层任务组织：了解和维护项目任务关系
结构化数据访问：针对AI处理优化的JSON格式响应
资源URI系统：干净的、类似RESTful的URI结构(todoist://project/{id}/tasks)

🛠️ 综合工具套件

CRUD操作：完成创建、读取、更新、删除功能
智能任务创建：自然语言截止日期和优先级设置
批量操作：高效处理多个任务和项目
错误处理：强大的错误管理和详细的反馈
🆕 已完成任务检索：通过具有灵活日期筛选功能的Sync API v9访问已完成的任务

🏗️ 高级体系结构

模块化设计结构

src/
├── handlers/
│   ├── mcpHandlers.ts    - Core MCP protocol handling
│   ├── projectHandler.ts - Advanced project management
│   └── taskHandler.ts    - Intelligent task operations
├── types/
│   └── todoist.ts        - TypeScript type definitions
├── utils/
│   └── todoistClient.ts  - Authenticated API client
└── index.ts              - Server initialization & logging

智能测井系统

基于文件的日志记录：不干扰stdio通信的非侵入式日志记录
详细请求跟踪：完成所有业务的审计跟踪
性能监控：执行时间和资源使用情况跟踪
调试友好：与MCP Inspector集成以进行开发

🎯 核心能力

📚 资源（读取操作）

资源URI	描述	用例
`todoist://today/tasks`	今天的计划任务	日常计划和重点
`todoist://project/{id}`	项目详细信息和元数据	项目管理
`todoist://project/{id}/tasks`	特定项目中的所有任务	项目任务概述
`todoist://project/{id}/structure`	完整的项目层次结构	复杂项目分析
`todoist://task/{id}`	单个任务详细信息	任务特定操作

🔧 工具（写入操作）

📖 阅读操作

get_todoist_projects -检索所有具有层次结构的项目
get_todoist_tasks -具有过滤功能的灵活任务检索
- 按项目ID筛选
- 按“今天”筛选当前任务
🆕 get_completed_tasks -使用自定义筛选器检索已完成的任务：
- 日期范围过滤（ISO 8601格式的自/至）
- 项目特定过滤
- 可配置的结果限制
🆕 get_today_completed_tasks -今天完成所有任务
🆕 get_week_completed_tasks -完成本周（周日至周六）的所有任务

✏️ 创建操作

create_todoist_project -使用颜色编码创建新项目
create_todoist_task -高级任务创建功能：
- 自然语言到期日
- 优先级（1-4）
- 项目分配
- 标签和说明

🔄 编辑操作

update_todoist_task -使用以下内容更新现有任务：
- 内容/标题更改
- 优先级调整（1-4）
- 到期日修改
- 标签管理
- 描述更新
move_todoist_task -在以下之间移动任务：
- 项目
- 项目中的章节
- 创建子任务（parentId）
update_todoist_project -更新项目属性：
- 项目名称
- 颜色主题
- 项目层次结构

✅ 国家运营

complete_todoist_task -将任务标记为已完成
reopen_todoist_task -重新打开已完成的任务

🗑️ 消除操作

delete_todoist_project -安全删除项目
delete_todoist_task -任务删除并确认

⚙️ 设置和配置

先决条件

Node.js 16+（推荐：Node.js 20+）
Todoist Pro帐户（用于API访问）
TypeScript 5.3+

安装

克隆和安装

git clone https://github.com/mariomosca/todoist-mcp-server.git
cd todoist-mcp-server
npm install

API令牌配置

从获取Todoist API代币 Todoist集成设置

方法1：环境文件

# Create .env file
echo "TODOIST_API_TOKEN=your_todoist_api_token_here" > .env

方法2：命令行令牌

# Pass token as argument
node build/index.js --token your_todoist_api_token_here

构建服务器

npm run build

Claude桌面集成

macOS配置: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "todoist-server": {
      "command": "/path/to/mcp-server-todoist/todoist-server/build/index.js",
      "args": ["--token", "your_todoist_api_token_here"]
    }
  }
}

Windows配置: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "todoist-server": {
      "command": "node",
      "args": ["/path/to/mcp-server-todoist/todoist-server/build/index.js", "--token", "your_todoist_api_token_here"]
    }
  }
}

🚀 开发与调试

开发工作流程

# Watch mode with auto-compilation
npm run watch

# Build production version
npm run build

# Start with HTTP server (development only)
npm run start:http

高级调试

由于MCP服务器通过stdio进行通信，调试需要特殊的工具：

# Launch MCP Inspector
npm run inspector

# View logs in real-time
tail -f todoist-mcp-server.log

Inspector提供了一个基于web的界面，用于测试所有服务器功能。

📖 使用示例

日常任务管理

Claude: "What tasks do I have today?"
→ Accesses todoist://today/tasks resource
→ Returns structured JSON with today's tasks

已完成任务分析

Claude: "What did I complete today?"
→ Uses get_today_completed_tasks tool
→ Returns all tasks completed with timestamps

Claude: "Show me my productivity for this week"
→ Uses get_week_completed_tasks tool
→ Returns comprehensive weekly completion report

自定义日期范围查询

Claude: "What tasks did I complete between Feb 1-5?"
→ Uses get_completed_tasks with since/until parameters
→ Returns filtered completed tasks from specific period

项目分析

Claude: "Show me the structure of my Work project"
→ Finds project ID for "Work"
→ Accesses todoist://project/{id}/structure
→ Returns hierarchical project view with subprojects

智能任务创建

Claude: "Create a high-priority task 'Review quarterly reports' due tomorrow in Work project"
→ Uses create_todoist_task tool
→ Automatically sets priority=4, due="tomorrow", finds Work project ID

批量操作

Claude: "Complete all tasks in my Personal project that are overdue"
→ Gets all Personal project tasks
→ Filters for overdue items
→ Completes each task individually

高级任务管理

Claude: "Change the priority of task 'Review quarterly reports' to high and move it to tomorrow"
→ Updates task priority to 4
→ Changes due date to tomorrow

任务组织

Claude: "Move the task 'Buy groceries' from Personal to Shopping project"
→ Moves task to different project using move_todoist_task

项目管理

Claude: "Rename my 'Work Stuff' project to 'Professional Tasks' and change color to blue"
→ Updates project name and color using update_todoist_project

🔬 技术创新

是什么让这个MCP服务器独一无二

🆕 同步API v9集成：利用Todoist Sync API进行已完成任务检索-这是标准REST API中不可用的功能，可实现全面的生产力分析。
德尔塔探测系统：与其他Todoist集成不同，此服务器可以跟踪自上次交互以来发生的更改，从而实现智能同步和更新操作。
分层资源映射：自动理解和映射复杂的项目层次结构，提供平面和结构化视图。
情境感知AI集成：专为AI交互模式而设计，具有优化的数据结构和清晰的操作分离。
高级错误恢复：强大的错误处理，为用户和人工智能系统提供可操作的反馈。
性能优化：高效使用API，支持智能缓存和批处理操作。
完成任务生命周期管理：完整的CRUD操作，包括其他Todoist集成中不常见的高级更新和移动功能。
灵活的任务组织：支持在项目、部分之间移动任务，以及创建具有父子关系的子任务。
项目管理集成双向项目更新，允许AI助手动态重组和维护项目结构。

🎯 AI结对编程卓越

该项目展示了先进 人工智能与人类协作方法:

人类建筑：战略决策、API设计和系统架构
人工智能实施：加速编码、模式实施和优化
协同测试：结合人类洞察力和人工智能驱动的边缘案例检测
迭代优化：通过人工智能辅助代码审查持续改进

🔮 路线图和扩展

计划的功能

[ ] 标签管理：完全支持Todoist标签和过滤器
[ ] 部门支持：项目部门创建和管理
[ ] 高级搜索：自然语言任务和项目搜索
[x] 分析集成：任务完成统计和生产力洞察（基本版本已完成）
[ ] Webhook支持：实时通知和同步
[ ] 多账户支持：处理多个Todoist帐户

整合机会

日历同步：与日历MCP服务器集成
笔记：与知识管理系统的联系
时间追踪：与时间跟踪MCP服务器集成
邮件集成：从电子邮件内容创建任务

🏆 投资组合展示

此MCP服务器展示了以下方面的专业知识：

高级TypeScript开发：复杂类型系统和异步模式
API集成体系结构：RESTful API消耗和状态管理
协议实现：符合模型上下文协议规范
错误处理和记录：生产就绪监控和调试
开发者体验：全面的工具和文件
人工智能工作流设计：针对AI助手交互模式进行了优化

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

🤝 贡献

欢迎投稿！请阅读我们的贡献指南，并提交任何改进请求。

建于❤️ 通过马里奥莫斯科 -展示人工智能与人类生产力协作的未来