AI导哈

任务管理服务器

一个为Todoist任务管理设计的本地MCP服务器，通过Model Context Protocol提供全面的任务管理功能。

  • by stevesimpson418
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 stevesimpson418/todoist-mcp-server

使用说明

Todoist MCP服务器

用于Todoist任务管理的本地MCP服务器，专为与Claude一起使用而设计。

包装Todoist REST v2和Sync API v1，以提供全面的任务管理 通过模型上下文协议实现功能。

特性

  • 任务CRUD --创建、读取、更新、完成、删除和移动任务
  • 批量操作 -通过同步API在单个API调用中更新多个任务
  • 项目管理 --列出项目，按名称解析（不区分大小写）
  • 标签 --为任务创建、重命名、删除和应用标签
  • 评论 --阅读任务并添加注释（支持Markdown）
  • 已完成的任务 --在日期范围内完成的查询任务（每周审查指标）
  • 优雅降级 -如果缺少API令牌，则服务器在没有Todoist工具的情况下启动

设置

1.获取Todoist API代币

首选 Todoist开发人员设置 并复制您的API令牌。

2.安装

git clone https://github.com/stevesimpson418/todoist-mcp-server.git
cd todoist-mcp-server

# Install dependencies (creates .venv/ in the project directory)
uv sync

紫外线新手？ uv sync 读取 pyproject.toml，创建了一个 .venv/ virtualenv内部 项目文件夹，并将所有依赖项安装到其中。您不需要激活它-- uv run <command> 自动处理。

3.配置环境

cp .env.example .env
# Edit .env and add your TODOIST_API_TOKEN

4.联系克劳德

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

提示： 跑 uv run which python 从项目目录中获取 command.

{
  "mcpServers": {
    "todoist": {
      "command": "/absolute/path/to/todoist-mcp-server/.venv/bin/python",
      "args": ["-m", "todoist_mcp_server.server"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

添加到Claude代码CLI

使用 claude mcp add 注册服务器的命令。这适用于任何目录。

claude mcp add --scope user todoist-mcp-server \
  --transport stdio \
  --env TODOIST_API_TOKEN=your_token_here \
  -- /path/to/todoist-mcp-server/.venv/bin/python -m todoist_mcp_server.server

替换 /path/to/todoist-mcp-server 使用克隆仓库的实际路径。

提示： 跑 uv run which python 从项目目录中获取确切信息 .venv/bin/python 命令的路径。

这 --scope user 标志保存到 ~/.claude.json 因此，服务器在所有项目中都是可用的。 没有它，命令默认为本地作用域（绑定到您运行它的任何目录）。 要将其范围改为单个项目，请使用 --scope project 它写入 .mcp.json 在 项目根。

要验证服务器是否已注册：

claude mcp list

添加后重新启动Claude Code。Todoist工具应出现在 /mcp 菜单。

注： Claude Code CLI使用与Claude Desktop不同的配置。这 claude mcp add 命令是注册MCP服务器的推荐方式——不要将它们添加到 ~/.claude/settings.json 因为该文件仅用于权限和挂钩。

更新

要获取最新版本并更新依赖关系，请执行以下操作：

cd /path/to/todoist-mcp-server
git pull
uv sync

更新后重新启动Claude Desktop或Claude Code CLI。

可用工具

工具 说明
list_todoist_projects 列出所有项目
get_project_tasks 从项目中获取任务
list_todoist_labels 列出所有标签
get_completed_tasks 按日期范围查询已完成的任务
get_task_comments 获取任务的评论
create_task 创建新任务
update_task 更新任务字段
move_task 将任务移动到另一个项目
complete_task 将任务标记为已完成
delete_task 永久删除任务
batch_update_tasks 批量更新多个任务
add_task_comment 向任务添加注释
create_todoist_label 创建新标签
rename_todoist_label 重命名标签
delete_todoist_label 删除标签

用法示例

每周回顾——看看你完成了什么：

1. get_completed_tasks(since="2026-03-28", until="2026-04-04")  → completed this week
2. list_todoist_projects()                                       → see all projects
3. get_project_tasks(project_name="Inbox")                       → triage leftover inbox tasks

跨项目重新组织任务：

1. get_project_tasks(project_name="Inbox")                          → find tasks to sort
2. move_task(task_id="123456", project_name="Home Renovation")      → move to the right project
3. batch_update_tasks(tasks=[
       {"id": "234567", "labels": ["waiting-on"]},
       {"id": "345678", "priority": 3}
   ])                                                               → bulk tidy-up

快速捕捉上下文：

1. create_task(
       content="Review pull request #42",
       project_name="Work",
       due_string="tomorrow 10am",
       priority=3
   )
2. add_task_comment(task_id="456789", content="See https://github.com/org/repo/pull/42")

发展

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest -v

# Run tests with coverage
uv run pytest --cov=todoist_mcp_server --cov-report=term-missing

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Install git hooks
lefthook install

本地 .env 文件

在Claude Desktop/Code之外手动运行服务器时（例如，用于开发或 调试），您可以创建 .env 项目根目录中的文件，以便服务器拾取 API令牌，而不传递环境变量：

TODOIST_API_TOKEN=your_token_here

这只是当地发展所需要的。Claude桌面和Claude代码CLI配置 通过直接传递此值 env 块。

发布

此项目使用 请释放 用于自动化 版本控制和发布。版本由以下因素决定 约定式提交:

  • fix: 提交bump 补丁 版本（例如0.1.0→ 0.1.1)
  • feat: 提交bump 次要的 版本（例如0.1.1→ 0.2.0)
  • BREAKING CHANGE 在提交页脚中颠簸 主要的 版本

当承诺土地 main，请打开（或更新）一个发布PR，该PR：

  • 将版本插入 pyproject.toml
  • 更新 CHANGELOG.md 带有分组条目

合并Release PR会自动创建一个git标签和GitHub Release。

包装与配送

此服务器目前通过git作为源代码分发。要安装：

git clone https://github.com/stevesimpson418/todoist-mcp-server.git
cd todoist-mcp-server
uv sync

这是目前本地stdio MCP服务器的标准分发模型。该项目是 已经配置为通过掀背车进行车轮制造，因此未来的分销选项包括：

  • PyPI --发布到PyPI，然后安装 uv tool install todoist-mcp-server 或 pip install todoist-mcp-server。需要向CI添加发布工作流。
  • uvx --一旦在PyPI上， uvx todoist-mcp-server 在不克隆仓库的情况下运行服务器。 Claude Desktop/Code配置将指向uvx管理的二进制文件，而不是本地文件 .venv.

许可证

麻省理工学院

相关 MCP