内容
# todoist-mcp
一款 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，将您的 Todoist 暴露为 Claude 的工具。通过 Claude Code 或任何兼容 MCP 的客户端，以自然语言管理任务、项目和部分。
## 功能
**任务**
- 使用 Todoist 过滤字符串列出任务（`today`、`overdue`、`p1 & !assigned to: others`等）
- 获取收件箱、今日任务或逾期任务
- 创建具有优先级、截止日期、描述、子任务和部分的任务
- 更新、完成、删除或移动任务
- 添加和删除评论
- 获取已完成任务历史
**项目**
- 列出、创建、重命名、归档、删除项目
- 在父项目下嵌套项目
**部分**
- 在项目中列出、创建、删除部分
**批量**
- `dump_all` — 一次调用获取所有任务、项目和部分，以进行全面分析
## 要求
- Python 3.13+
- [uv](https://docs.astral.sh/uv/)
- 具有 [API令牌](https://app.todoist.com/app/settings/integrations/developer) 的 Todoist 账户
## 设置
### 1. 克隆和安装
```bash
git clone https://github.com/neilli1992/todoist-mcp
cd todoist-mcp
uv sync
```
### 2. 配置凭证
创建 `.env` 文件（gitignored）：
```
TODOIST_TOKEN=your_api_token_here
TODOIST_API=https://api.todoist.com/api/v1
```
### 3. 配置项目映射
`client.py` 包含一个 `PROJECTS` 字典，将人类可读的名称映射到 Todoist 项目 ID。用您自己的项目更新它 — 服务器使用这些进行名称到 ID 的解析，以便您可以按名称而不是 ID 引用项目。
从 Todoist API 获取项目 ID：
```bash
curl -s https://api.todoist.com/api/v1/projects \
-H "Authorization: Bearer YOUR_TOKEN" | python3 -m json.tool | grep -E '"id"|"name"'
```
### 4. 在 Claude Code 中注册
在 `~/.claude/settings.json` 中添加以下内容到 `mcpServers` 下：
```json
{
"mcpServers": {
"todoist": {
"command": "uv",
"args": ["run", "mcp", "run", "server.py"],
"cwd": "/path/to/todoist-mcp"
}
}
}
```
重启 Claude Code。`mcp__todoist__*` 工具将自动出现。
## 用法
注册后，直接与 Claude 对话：
```
我的收件箱里有什么？
在健康项目中创建一个任务 “预约牙医”，截止到下周，优先级为 P2
将牙医任务移动到家庭项目
给我展示所有逾期的任务
转储所有任务，以便我们进行每周回顾
```
## 脚本
`scripts/review.py` — 每日回顾：打印逾期 + 今日 + 收件箱
`scripts/triage.py` — 收件箱分类，带有路由提示
```bash
uv run python scripts/review.py
uv run python scripts/triage.py
```
## 优先级映射
Todoist 的内部优先级与 UI 标签相反：
| UI 标签 | API 值 |
|----------|-----------|
| P1 | 4 |
| P2 | 3 |
| P3 | 2 |
| P4 | 1 |
服务器接受 `P1`/`P2`/`P3`/`P4` 字符串并自动转换。
## 项目结构
```
server.py — MCP 服务器（FastMCP），所有工具定义
client.py — Todoist REST API 客户端，由服务器和脚本共享
scripts/ — 独立的 CLI 脚本
```
