MCP Todoist

一个模型上下文协议 (MCP) 服务器，使 Claude 能够与您的 Todoist 帐户交互。

功能

• 管理任务：创建、更新、完成和删除任务
• 在项目中和使用标签组织任务
• 根据各种条件搜索和过滤任务
• 与 Claude Desktop 无缝集成

前提条件

• Python 3.11+
• Astral UV
• Todoist 帐户 和 API 令牌
• Claude Desktop（用于使用 MCP 服务器）

快速开始

1. 安装

# 使用 UV 安装
uvx mcp-todoist

2. 配置

1. 从 Todoist 集成设置 获取您的 Todoist API 令牌

2. 配置环境变量：

   # 添加到您的 .env 文件或环境变量
   TODOIST_API_TOKEN=your_api_token_here
   

3. 配置 Claude Desktop：

   // ~/.config/claude/claude_desktop_config.json 或等效文件
   {
     "mcpServers": {
       "mcp-todoist": {
         "command": "uvx",
         "args": ["mcp-todoist"]
       }
     }
   }
   

3. 与 Claude 一起使用

配置完成后，您可以要求 Claude 与您的 Todoist 帐户交互：

• "显示我今天到期的任务"
• "创建一个新任务，明天购买杂货"
• "将我的 '发送电子邮件' 任务标记为已完成"
• "创建一个名为 '房屋装修' 的新项目"
• "显示我的 '工作' 项目中的所有任务"

可用工具

任务管理

• list-tasks - 检索和过滤任务
• create-task - 创建新任务
• update-task - 更新现有任务
• complete-task - 将任务标记为已完成
• delete-task - 删除任务

项目管理

• list-projects - 获取所有项目
• create-project - 创建新项目
• update-project - 更新项目
• delete-project - 删除项目

标签管理

• list-labels - 获取所有标签
• create-label - 创建新标签
• update-label - 更新标签
• delete-label - 删除标签

实用工具

• search - 使用复杂过滤搜索任务

运行 MCP 服务器

有多种方法可以运行 Todoist MCP 服务器：

方法 1：直接命令行

在终端窗口中运行服务器：

# 设置您的 API 令牌
export TODOIST_API_TOKEN=your_api_token_here

# 使用 UV 运行服务器
uvx mcp-todoist

# 替代方法：从源代码运行
cd /path/to/mcp-todoist
uv run python -m mcp_todoist

在使用 Claude Desktop 时，保持此终端窗口打开。

方法 2：使用启动脚本（推荐）

创建一个启动脚本，Claude Desktop 可以使用该脚本自动启动服务器：

1. 创建一个名为 start-todoist-mcp.sh 的文件，内容如下：

#!/bin/bash

# 设置环境变量
export MCP_SERVER_NAME="mcp-todoist"
export MCP_LOG_LEVEL="INFO"
export MCP_DEBUG="true"
export TODOIST_API_TOKEN="your_todoist_api_token_here"

# Todoist MCP 服务器的路径
MCP_PATH="/path/to/mcp-todoist"

# 用于调试的日志文件
LOG_FILE="${MCP_PATH}/todoist-mcp.log"

# 创建日志文件或清除现有文件
echo "Starting Todoist MCP server at $(date)" > "${LOG_FILE}"

# 导航到项目目录
cd "${MCP_PATH}"

# 启动 MCP 服务器
echo "Starting MCP server from ${MCP_PATH}" >> "${LOG_FILE}"
uv run python -m mcp_todoist >> "${LOG_FILE}" 2>&1

2. 使脚本可执行：

chmod +x start-todoist-mcp.sh

3. 更新您的 Claude Desktop 配置以使用此脚本：

{
  "mcpServers": {
    "mcp-todoist": {
      "command": "/absolute/path/to/start-todoist-mcp.sh",
      "args": []
    }
  }
}

这种方法有几个优点：

• 服务器与 Claude Desktop 自动启动
• 所有日志都捕获在一个文件中，以便于调试
• 环境变量设置一致

调试

如果您遇到 MCP 服务器的问题，以下是一些调试策略：

1. 检查日志

如果使用启动脚本，请检查日志文件：

cat /path/to/mcp-todoist/todoist-mcp.log

2. 启用调试模式

将 MCP_DEBUG 环境变量设置为 true 以进行更详细的日志记录：

export MCP_DEBUG=true
uvx mcp-todoist

3. 验证 API 令牌

确保您的 Todoist API 令牌正确且仍然有效：

# 使用简单的 curl 请求测试令牌
curl -X GET \
  https://api.todoist.com/rest/v2/projects \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

4. 使用 MCP Inspector

MCP Inspector 是一个强大的工具，用于调试 MCP 服务器：

npx @modelcontextprotocol/inspector uvx mcp-todoist

这将打开一个 Web 界面，显示 Claude 和 MCP 服务器之间的所有通信。

5. 常见问题和解决方案

• "MCP Server not available" 错误: 确保服务器在单独的终端中或通过启动脚本运行。
• 身份验证错误: 检查您的 Todoist API 令牌是否在您的环境中正确设置。
• "Command not found" 错误: 确保已安装 Astral UV 并且在您的 PATH 中。
• 超时错误: 如果您的 MCP 服务器响应缓慢，请尝试增加 Claude Desktop 设置中的超时时间。

开发

设置

# 克隆存储库
git clone https://github.com/yourusername/mcp-todoist.git
cd mcp-todoist

# 安装依赖项
uv sync

测试

# 运行测试
uv run pytest

本地开发

对于本地开发，您可以创建一个包含您的 Todoist API 令牌的 .env 文件：

TODOIST_API_TOKEN=your_api_token_here

然后运行服务器：

uv run python -m mcp_todoist

许可证

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。