npm package: @hangox/todoist-mcp-server
Description: Todoist MCP 服务器 - 通过 MCP 协议操作 Todoist 任务
Author: hangox
Latest version: 1.0.1

# Todoist MCP 服务器

这是一个用 TypeScript 编写的 Todoist MCP (Model Context Protocol) 服务器,允许通过 MCP 协议与 Todoist API 进行交互。

## 功能特性

- ✅ **读取任务** - 获取任务列表,支持多种筛选条件
- ✅ **创建任务** - 创建新任务,支持完整的任务属性
- ✅ **更新任务** - 修改现有任务的属性
- ✅ **删除任务** - 删除指定任务
- ✅ **完成任务** - 标记任务为已完成
- ✅ **重新打开任务** - 重新激活已完成的任务

## 前置要求

- Node.js 18 或更高版本
- Todoist 账号和 API Token

## 获取 Todoist API Token

1. 登录 [Todoist](https://todoist.com)
2. 进入 **设置 → 集成 → 开发者**
3. 复制你的 API Token

## 安装和配置

### 方式一: 通过 npm 安装(推荐)

这是最简单的安装方式,无需克隆仓库或编译代码。

#### 1. 全局安装

```bash
npm install -g @hangox/todoist-mcp-server
```

或使用其他包管理器:

```bash
# pnpm
pnpm add -g @hangox/todoist-mcp-server

# yarn
yarn global add @hangox/todoist-mcp-server
```

#### 2. 在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

添加以下配置(推荐使用 npx,无需安装):

```json
{
  "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. 克隆仓库

```bash
git clone https://gitlab.com/hango/code-test-cc.git
cd code-test-cc/todoist_mcp
```

#### 2. 安装依赖

```bash
npm install
```

#### 3. 编译项目

```bash
npm run build
```

#### 4. 在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件,添加以下配置:

```json
{
  "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` (可选): 项目ID
- `section_id` (可选): 分区ID
- `label` (可选): 标签名称
- `filter` (可选): Todoist 过滤器表达式,如 "today" 或 "priority 1"

**示例**:
```
获取所有任务
获取今天的任务 (filter: "today")
获取高优先级任务 (filter: "priority 1")
```

### 2. get-task
根据任务ID获取单个任务的详细信息。

**参数**:
- `task_id` (必填): 任务ID

### 3. create-task
创建新任务。

**参数**:
- `content` (必填): 任务标题
- `description` (可选): 任务描述
- `project_id` (可选): 项目ID
- `priority` (可选): 优先级 (1-4, 4为最高)
- `due_string` (可选): 截止日期的自然语言描述,如 "明天" 或 "下周一"
- `due_date` (可选): 截止日期,格式为 YYYY-MM-DD
- `labels` (可选): 标签数组

**示例**:
```
创建一个任务 "完成项目报告",优先级为4,截止日期是明天
```

### 4. update-task
更新现有任务。

**参数**:
- `task_id` (必填): 任务ID
- `content` (可选): 新的任务标题
- `description` (可选): 新的任务描述
- `priority` (可选): 新的优先级
- `due_string` (可选): 新的截止日期

**示例**:
```
将任务 123456 的优先级改为 4
```

### 5. delete-task
删除任务。

**参数**:
- `task_id` (必填): 要删除的任务ID

### 6. close-task
完成(关闭)任务。

**参数**:
- `task_id` (必填): 要完成的任务ID

### 7. reopen-task
重新打开已完成的任务。

**参数**:
- `task_id` (必填): 要重新打开的任务ID

## 开发命令

```bash
# 编译项目
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 REST API 文档](https://developer.todoist.com/rest/v2/)

## 故障排查

### 服务器无法启动

1. 确认已设置 `TODOIST_API_TOKEN` 环境变量
2. 检查 API Token 是否有效
3. 确认 Node.js 版本 >= 18

### 在 Claude Desktop 中看不到工具

1. 检查配置文件路径是否正确
2. 确认 JSON 格式正确(没有语法错误)
3. 重启 Claude Desktop
4. 查看 Claude Desktop 的日志文件

### API 请求失败

1. 检查网络连接
2. 确认 API Token 有效且未过期
3. 查看错误消息了解具体问题

## 快速开始示例

安装并配置完成后,你可以在 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

## 相关链接

- [Todoist 官网](https://todoist.com)
- [Todoist API 文档](https://developer.todoist.com/rest/v2/)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Claude Desktop](https://claude.ai/download)