Todoist MCP

官方

直接从您的LLM管理Todoist任务和项目。

GitHub

541

试用此 MCP赞助

你可以用 Todoist MCP 做什么？

按日期查找任务 — 让您的助手使用 findTasksByDate 查找特定日期的任务。
添加新任务 — 让您的助手通过 addTasks 工具为您创建一个或多个 Todoist 任务。
检查账户身份 — 在进行更改之前，使用 user-info 询问已连接的是哪个 Todoist 账户，以确认当前用户。
直接运行工具 — 使用 npm run tool 以 JSON 参数独立执行任何工具，绕过 MCP 服务器。

文档

Todoist MCP 服务器

用于将 AI 代理连接到 Todoist 的库。包含可集成到 LLM 中的工具，使它们能够代表用户访问和修改 Todoist 账户。

这些工具既可以通过 MCP 服务器使用，也可以直接导入到其他项目中，集成到您自己的 AI 对话界面中。

使用工具

1. 将此仓库添加为依赖项

npm install @doist/todoist-mcp

2. 导入工具并将其接入 AI

以下是使用 Vercel 的 AI SDK 的示例。

import { findTasksByDate, addTasks } from '@doist/todoist-mcp'
import { TodoistApi } from '@doist/todoist-sdk'
import { streamText } from 'ai'

// Create Todoist API client
const client = new TodoistApi(process.env.TODOIST_API_KEY)

// Helper to wrap tools with the client
function wrapTool(tool, todoistClient) {
    return {
        ...tool,
        execute(args) {
            return tool.execute(args, todoistClient)
        },
    }
}

const result = streamText({
    model: yourModel,
    system: 'You are a helpful Todoist assistant',
    tools: {
        findTasksByDate: wrapTool(findTasksByDate, client),
        addTasks: wrapTool(addTasks, client),
    },
})

作为 MCP 服务器使用

快速开始

您可以直接使用 npx 运行 MCP 服务器：

npx @doist/todoist-mcp

设置指南

Todoist MCP 服务器以可流式传输的 HTTP 服务形式提供，便于与各种 AI 客户端集成：

主 URL（可流式传输 HTTP）： https://ai.todoist.net/mcp

Claude Desktop

打开设置 → 连接器 → 添加自定义连接器
输入 https://ai.todoist.net/mcp 并完成 OAuth 身份验证

Cursor

创建配置文件：

全局： ~/.cursor/mcp.json
项目特定： .cursor/mcp.json

{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]
        }
    }
}

如有提示，请在 Cursor 设置中启用服务器。

Claude Code (CLI)

最快的设置方式是使用官方 Todoist 插件，它会为您自动配置 MCP 服务器：

/plugin marketplace add doist/todoist-mcp
/plugin install todoist@doist

首次使用 Todoist 工具时，OAuth 将在您的浏览器中运行。更多信息请参阅 Anthropic 的插件文档。

如果您更愿意手动配置 MCP 服务器，请运行：

claude mcp add --transport http todoist https://ai.todoist.net/mcp

然后启动 claude，执行 /mcp，并选择 todoist MCP 服务器进行身份验证。

Visual Studio Code

打开命令面板 → MCP：添加服务器
选择 HTTP 传输方式并使用：

{
    "servers": {
        "todoist": {
            "type": "http",
            "url": "https://ai.todoist.net/mcp"
        }
    }
}

其他 MCP 客户端

npx -y mcp-remote https://ai.todoist.net/mcp

有关设置和使用 MCP 服务器的更多详细信息（包括创建自定义服务器），请参阅 docs/mcp-server.md。

功能特性

该项目的一个关键特性是工具可以复用，并非专门为 MCP 服务器使用而编写。它们可以作为工具接入其他对话式 AI 界面（例如 Vercel 的 AI SDK）。

该项目仍处于早期阶段。预计很快会有更多和/或更好的工具。

尽管如此，我们的目标是提供一小组能够实现完整工作流程的工具，而不仅仅是原子操作，在灵活性和效率之间为 LLM 取得平衡。

有关我们的设计理念、指南和开发模式，请参阅 docs/tool-design.md。

可用工具

有关可用工具的完整列表，请参阅 src/tools 目录。

OpenAI MCP 兼容性

此服务器包含遵循 OpenAI MCP 规范的 search 和 fetch 工具，可实现与 OpenAI MCP 协议的无缝集成。这些工具返回针对 OpenAI 要求优化的 JSON 编码结果，同时保持与更广泛的 MCP 生态系统的兼容性。

依赖项

使用官方 @modelcontextprotocol/server 的 MCP 服务器
Todoist TypeScript API 客户端 @doist/todoist-sdk

MCP 服务器设置

有关设置 MCP 服务器的完整说明，请参阅 docs/mcp-server.md。

本地开发设置

有关完整的设置说明，请参阅 docs/dev-setup.md；有关贡献者工作流程和质量检查，请参阅 CONTRIBUTING.md。

MCP Apps

该项目包含对 MCP Apps 的支持——即在 AI 聊天界面中内联渲染的交互式 UI 小部件。小部件提供工具输出的丰富可视化表示（例如任务列表），而不是纯文本。

有关小部件架构、构建流程和开发工作流程，请参阅 docs/mcp-apps.md。

快速开始

克隆并设置好仓库后：

npm start - 构建并运行 MCP 检查器以进行测试
npm run dev - 开发模式，支持自动重建和重启
npm run tool:list - 列出可直接执行的可用工具
npm run tool -- <tool-name> '<json-args>' - 无需 MCP 直接运行工具

使用 npm run tool 时，请在工具参数前包含 --，以便 npm 将它们转发给 scripts/run-tool.ts。

写入操作前的示例检查：

npm run tool -- user-info '{}'

这可以确认当前 TODOIST_API_KEY 连接的是哪个 Todoist 账户。

run-tool 使用您 .env 文件中的 TODOIST_API_KEY（由 npm run setup 从 .env.example 创建）。运行写入操作时，请使用测试账户或临时项目，以避免修改真实数据。

贡献

请参阅 CONTRIBUTING.md 了解：

开发工作流程
使用 scripts/run-tool.ts 直接运行工具
测试和质量检查
提交约定

发布

该项目使用 release-please 来自动化版本管理和包发布。

工作原理

使用 Conventional Commits 进行更改：
- feat: 用于新功能（次版本号递增）
- fix: 用于错误修复（补丁版本号递增）
- feat!: 或 fix!: 用于破坏性更改（主版本号递增）
- docs: 用于文档更改
- chore: 用于维护任务
- ci: 用于 CI 更改
当提交推送到 main 时：
- Release-please 自动创建/更新发布 PR
- PR 包含版本号递增和变更日志更新
- 审阅 PR 并在准备好后合并
合并发布 PR 后：
- 自动创建新的 GitHub 发布
- 创建新标签
- 触发 publish 工作流
- 包发布到 npm