# @doist/todoist-mcp 中文文档

规范地址：https://npmcn.com/package/%40doist/todoist-mcp/

版本：14\.0\.5
npm 元数据更新时间：2026-11-11T13:44:15.980Z
中文译文更新时间：2026-11-12T14:54:12.583Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40doist/todoist-mcp
原文对照：https://npmcn.com/package/%40doist/todoist-mcp/?lang=original
项目主页：https://github.com/todoist/todoist-mcp#readme
源码仓库：https://github.com/todoist/todoist-mcp

弃用说明：Moved to @todoist/mcp\. Update dependencies and MCP client configs, e\.g\. npx -p @todoist/mcp todoist-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.9 MB，197 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：9 个
- peer 依赖：@modelcontextprotocol/node ^2\.1\.0，@modelcontextprotocol/server ^2\.2\.0
- 首次发布：2026-05-14T13:37:03.348Z
- 最新版本发布：2026-11-11T11:35:36.917Z
- 近 30 天下载量：28363（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：88（近 12 个月 88 个）

## 中文简介

官方 Todoist MCP 服务器

## 安装

```sh
npm install @doist/todoist-mcp
```

也可以使用：`pnpm add @doist/todoist-mcp`、`yarn add @doist/todoist-mcp`、`bun add @doist/todoist-mcp`

## README

# Todoist MCP 服务器

连接 AI 代理到 Todoist 的库 。 包括可纳入LLMS的工具, 以用户的名义访问和修改 Todoist 账户.

这些工具既可以通过MCP服务器使用,也可以直接从其他项目导入到 将它们集成到您的 AI 对话界面中 .

## 使用工具

### 1\. 将此寄存器添加为依赖

```sh
npm install @doist/todoist-mcp
```

### 2\. 进口工具并插入AI

举个例子 [Vercel的人工智能SDK](https://ai-sdk.dev/docs/ai-sdk-core/generating-text#streamtext)。 。 。 .

```js
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 服务器 :

```bash
npx @doist/todoist-mcp
```

### 设置指南

Todoist MCP服务器作为可流的HTTP服务提供,便于与各种AI客户端进行集成:

**主 URL( Streamable HTTP) :** `https://ai.todoist.net/mcp`

#### 克劳德桌面

1.  打开设置 — 连接器 — 添加自定义连接器
2.  输入 `https://ai.todoist.net/mcp` 并完成 OAuth 认证

#### 光标

创建配置文件 :

-   **全球:** `~/.cursor/mcp.json`
-   **具体项目:** `.cursor/mcp.json`

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

如果提示, 则启用光标设置中的服务器 .

#### 克劳德代码( CLI)

最快的设置是正式的托多主义插件,它为您连接了MCP服务器:

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

OAuth在浏览器中运行,这是你第一次使用 Todoist 工具. 见 [Anthropic 插件文件](https://code.claude.com/docs/en/plugins-reference) 为了更多.

如果您宁愿手动配置 MCP 服务器, 请运行 :

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

然后发射 `claude`执行 `/mcp`,并选择 `todoist` MCP服务器认证.

#### 双子座CLI

使用 [双子座CLI](https://geminicli.com/docs/get-started/installation/) 0.67.0 或以后:

```bash
gemini extensions install https://github.com/todoist/todoist-mcp
```

开始或重新启动双子座 CLI, 然后运行 `/mcp auth todoist` 并签入你的托多主义账户。 Todoist主机服务器;不需要 API 密钥或本地服务器.

助理可以读取和更改您的托多主义任务和项目. 在设置 – 集成 下随时取消 Todoist 的访问 .

#### 视觉工作室代码

1.  打开命令调色板 — MCP: 添加服务器
2.  选择 HTTP 传输和使用 :

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

#### 其他MCP客户端

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

关于建立和使用MCP服务器,包括创建自定义服务器的更详细情况,请参见 [文件/mcp-server.md](https://npmcn.com/package/%40doist/todoist-mcp/docs/mcp-server.md)。 。 。 .

## 特征

该项目的一个关键特征是工具可以被再用,而不是专门写作用于MCP服务器. 它们可以作为工具与其它对话AI接口(如Vercel的AI SDK)相接.

该项目尚处于初期阶段。 希望很快有更多的和/或更好的工具.

尽管如此,我们的目标是提供一套小的工具,使整个工作流程成为可能,而不仅仅是原子行动,在LLMs的灵活性和效率之间取得平衡.

关于我们的设计理念、方针和发展模式,见 [文件/工具设计](https://npmcn.com/package/%40doist/todoist-mcp/docs/tool-design.md)。 。 。 .

### 可用工具

关于现有工具的完整清单,见 [斜弧/工具](https://npmcn.com/package/%40doist/todoist-mcp/src/tools) 目录.

#### OpenAI MCP 兼容性

此服务器包括 `search` 财务报告和审定财务报表 `fetch` 工具 [OpenAI MCP 规格](https://platform.openai.com/docs/mcp),允许与OpenAI的MCP协议进行无缝集成. 这些工具返回了JSON编码结果,优化了OpenAI的要求,同时保持了与更广泛的MCP生态系统的相容性.

## 依赖关系

-   使用官方的 MCP 服务器 [@ modelcontextprotocol/ 服务器](https://github.com/modelcontextprotocol/typescript-sdk)
-   Todoist Typescript API 客户端 [@ doist/todoist-sdk (英语)](https://github.com/Doist/todoist-sdk)

## MCP 服务器设置

见 [文件/mcp-server.md](https://npmcn.com/package/%40doist/todoist-mcp/docs/mcp-server.md) 用于设置 MCP 服务器的完整指令.

## 本地开发设置

见 [文件/设置](https://npmcn.com/package/%40doist/todoist-mcp/docs/dev-setup.md) 完整设置指令和 [捐款额](https://npmcn.com/package/%40doist/todoist-mcp/CONTRIBUTING.md) 用于贡献者工作流程和质量检查.

### MCP 应用程序

本项目包括支助 **MCP 应用程序** – 交互式 UI 部件在 AI 聊天界面中实现内化 。 部件提供了丰富的工具输出的视觉表现(例如任务列表)而不是纯文本.

见 [文档/mcp-apps.md](https://npmcn.com/package/%40doist/todoist-mcp/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 记录当前 `TODOIST_API_KEY` 连接到.

`run-tool` 用途 `TODOIST_API_KEY` 从你的 `.env` 文件( 创建于 `.env.example` 以 `npm run setup`) (中文(简体) ). 在运行写入操作时使用测试账户或临时项目来避免修改真实数据.

## 捐款

见 [捐款额](https://npmcn.com/package/%40doist/todoist-mcp/CONTRIBUTING.md) 用于:

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

## 释放

这个项目使用 [请放行](https://github.com/googleapis/release-please) 实现版本管理和软件包出版的自动化.

### 如何运作

1.  使用 [常规武器委员会](https://www.conventionalcommits.org/)数字 :
    
    -   `feat:` 用于新特性(小版本起伏)
    -   `fix:` 对于错误修正( patch 版本出错)
    -   `feat!:` 或者说 `fix!:` 用于断开更改(主要版本出错)
    -   `docs:` 文件更改
    -   `chore:` 维修任务
    -   `ci:` cI 修改
2.  当犯罪被逼迫 `main`数字 :
    
    -   释放请自动创建/更新释放的 PR
    -   PR 包括版本凸起和更改日志更新
    -   审查公关, 准备好后合并
3.  合并发布 PR 后 :
    
    -   自动创建新的 GitHub 发布
    -   创建了新标签
    -   这个 `publish` 启动工作流程
    -   软件包发布到 npm

## 常见问题

### @doist/todoist-mcp 是什么？

官方 Todoist MCP 服务器注意：该包已被作者标记为弃用——Moved to @todoist/mcp\. Update dependencies and MCP client configs, e\.g\. npx -p @todoist/mcp todoist-mcp

### 如何安装 @doist/todoist-mcp？

在项目目录运行 npm install @doist/todoist-mcp，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@modelcontextprotocol/node（^2\.1\.0）、@modelcontextprotocol/server（^2\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 todoist-mcp、todoist-mcp-http，可以用 npx todoist-mcp 直接运行。

### @doist/todoist-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @doist/todoist-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @doist/todoist-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @doist/todoist-mcp 可以商用吗？

@doist/todoist-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @doist/todoist-mcp 的下载量有多少？

根据 npm 官方下载统计，@doist/todoist-mcp 在 2026/10/13 – 2026/11/11 这 30 天内被下载 28,363 次，日均约 945 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @doist/todoist-mcp 还在维护吗？

最新版本 14\.0\.5 发布于 2026/11/11（2 天前）；至今共发布 88 个版本，其中过去 12 个月发布了 88 个；首次发布于 2026/05/14。作者已将其标记为弃用，新项目建议寻找替代方案。