@hangox/todoist-mcp-server
v1.0.1
Published
Todoist MCP 服务器 - 通过 MCP 协议操作 Todoist 任务
Maintainers
hangoxReadme
Todoist MCP 服务器
这是一个用 TypeScript 编写的 Todoist MCP (Model Context Protocol) 服务器,允许通过 MCP 协议与 Todoist API 进行交互。
功能特性
- ✅ 读取任务 - 获取任务列表,支持多种筛选条件
- ✅ 创建任务 - 创建新任务,支持完整的任务属性
- ✅ 更新任务 - 修改现有任务的属性
- ✅ 删除任务 - 删除指定任务
- ✅ 完成任务 - 标记任务为已完成
- ✅ 重新打开任务 - 重新激活已完成的任务
前置要求
- Node.js 18 或更高版本
- Todoist 账号和 API Token
获取 Todoist API Token
- 登录 Todoist
- 进入 设置 → 集成 → 开发者
- 复制你的 API Token
安装和配置
方式一: 通过 npm 安装(推荐)
这是最简单的安装方式,无需克隆仓库或编译代码。
1. 全局安装
npm install -g @hangox/todoist-mcp-server或使用其他包管理器:
# pnpm
pnpm add -g @hangox/todoist-mcp-server
# yarn
yarn global add @hangox/todoist-mcp-server2. 在 Claude Desktop 中配置
编辑 Claude Desktop 配置文件:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
添加以下配置(推荐使用 npx,无需安装):
{
"mcpServers": {
"todoist": {
"command": "npx",
"args": ["-y", "@hangox/todoist-mcp-server"],
"env": {
"TODOIST_API_TOKEN": "your_api_token_here"
}
}
}
}3. 重启 Claude Desktop
配置完成后,重启 Claude Desktop 以加载 MCP 服务器。
方式二: 从源码安装
如果你想从源码构建或进行开发,可以使用这种方式。
1. 克隆仓库
git clone https://gitlab.com/hango/code-test-cc.git
cd code-test-cc/todoist_mcp2. 安装依赖
npm install3. 编译项目
npm run build4. 在 Claude Desktop 中配置
编辑 Claude Desktop 配置文件,添加以下配置:
{
"mcpServers": {
"todoist": {
"command": "node",
"args": ["/path/to/code-test-cc/todoist_mcp/build/index.js"],
"env": {
"TODOIST_API_TOKEN": "your_api_token_here"
}
}
}
}注意: 将 /path/to/code-test-cc/todoist_mcp 替换为项目的实际路径。
5. 重启 Claude Desktop
配置完成后,重启 Claude Desktop 以加载 MCP 服务器。
可用工具
1. get-tasks
获取任务列表,支持多种筛选条件。
参数:
project_id(可选): 项目IDsection_id(可选): 分区IDlabel(可选): 标签名称filter(可选): Todoist 过滤器表达式,如 "today" 或 "priority 1"
示例:
获取所有任务
获取今天的任务 (filter: "today")
获取高优先级任务 (filter: "priority 1")2. get-task
根据任务ID获取单个任务的详细信息。
参数:
task_id(必填): 任务ID
3. create-task
创建新任务。
参数:
content(必填): 任务标题description(可选): 任务描述project_id(可选): 项目IDpriority(可选): 优先级 (1-4, 4为最高)due_string(可选): 截止日期的自然语言描述,如 "明天" 或 "下周一"due_date(可选): 截止日期,格式为 YYYY-MM-DDlabels(可选): 标签数组
示例:
创建一个任务 "完成项目报告",优先级为4,截止日期是明天4. update-task
更新现有任务。
参数:
task_id(必填): 任务IDcontent(可选): 新的任务标题description(可选): 新的任务描述priority(可选): 新的优先级due_string(可选): 新的截止日期
示例:
将任务 123456 的优先级改为 45. delete-task
删除任务。
参数:
task_id(必填): 要删除的任务ID
6. close-task
完成(关闭)任务。
参数:
task_id(必填): 要完成的任务ID
7. reopen-task
重新打开已完成的任务。
参数:
task_id(必填): 要重新打开的任务ID
开发命令
# 编译项目
npm run build
# 监听模式编译
npm run watch
# 运行服务器(需要先编译)
npm start
# 开发模式(编译并运行)
npm run dev项目结构
todoist_mcp/
├── src/
│ ├── index.ts # MCP 服务器主入口
│ ├── todoist-client.ts # Todoist API 客户端封装
│ └── types.ts # TypeScript 类型定义
├── build/ # 编译输出目录
├── package.json
├── tsconfig.json
├── CLAUDE.MD # 项目说明
└── README.md # 使用文档API 文档
本项目使用 Todoist REST API v2。更多信息请参考:
故障排查
服务器无法启动
- 确认已设置
TODOIST_API_TOKEN环境变量 - 检查 API Token 是否有效
- 确认 Node.js 版本 >= 18
在 Claude Desktop 中看不到工具
- 检查配置文件路径是否正确
- 确认 JSON 格式正确(没有语法错误)
- 重启 Claude Desktop
- 查看 Claude Desktop 的日志文件
API 请求失败
- 检查网络连接
- 确认 API Token 有效且未过期
- 查看错误消息了解具体问题
快速开始示例
安装并配置完成后,你可以在 Claude Desktop 中直接使用自然语言操作 Todoist:
你: 帮我创建一个任务 "完成项目报告",优先级设为最高,截止日期是明天
Claude: 好的,我来为你创建这个任务...
[调用 create-task 工具]
任务创建成功! 任务ID: 123456789
你: 查看我今天的所有任务
Claude: 让我查看你今天的任务列表...
[调用 get-tasks 工具,使用 filter: "today"]
你今天有 3 个任务:
1. 完成项目报告 (优先级: 4)
2. ...发布信息
- npm 包名:
@hangox/todoist-mcp-server - 当前版本: 1.0.1
- npm 主页: https://www.npmjs.com/package/@hangox/todoist-mcp-server
- 仓库地址: https://gitlab.com/hango/code-test-cc/tree/master/todoist_mcp
更新日志
v1.0.1 (2025-10-15)
文档更新:
- 🐛 修复 README 中的 MCP 配置示例
- 📝 移除不正确的全局命令配置方式
- ✅ 保留正确的 npx 配置方式
v1.0.0 (2025-10-15)
初始版本发布:
- ✅ 完整实现 Todoist REST API v2 集成
- ✅ 支持 7 个核心工具:读取、创建、更新、删除、完成、重新打开任务
- ✅ TypeScript 类型安全
- ✅ 完整的错误处理和中文提示
- ✅ 支持 npm 全局安装
许可证
MIT
贡献
欢迎提交 Issue 和 Pull Request!
- 问题反馈: https://gitlab.com/hango/code-test-cc/issues
- 功能建议: 欢迎在 Issue 中提出
作者
hangox