使用说明

项目简介

本项目是一个MCP（Model Context Protocol）服务器，旨在使大型语言模型（LLM），如Claude，能够与Todoist任务管理应用进行交互。通过此服务器，LLM客户端可以利用自然语言指令，调用Todoist的功能，实现任务的创建、检索、更新和完成等操作，从而提升用户的任务管理效率。

主要功能点

任务创建：允许LLM创建新的Todoist任务，可以指定任务内容以及可选的描述、截止日期和优先级等属性。
任务检索：支持通过任务ID或各种过滤条件（如项目、标签、优先级、是否逾期等）检索Todoist任务列表。
任务管理：提供更新任务属性、标记任务完成和删除任务的功能。

安装步骤

克隆仓库

git clone [email protected]/Johnxjp/todoist-mcp-python.git
cd todoist-mcp-python

安装依赖 确保已安装 Python 3.12 和 uv。然后，根据仓库 'README.md' 的指示，使用 uv 安装项目依赖：

uv pip install -r requirements.txt # 如果有 requirements.txt 文件
# 或者根据 README 安装 mcp 和 todoist_api_python
uv pip install mcp[cli] todoist_api_python

配置 Todoist API Token 访问 Todoist开发者页面获取 API Token，并将其设置为环境变量 'TODOIST_API_TOKEN'。例如，在 Linux 或 macOS 中，可以执行：

export TODOIST_API_TOKEN="YOUR_API_TOKEN"

或在 Windows PowerShell 中：

$env:TODOIST_API_TOKEN="YOUR_API_TOKEN"

服务器配置

MCP客户端（如Claude）需要配置以下JSON信息以连接到此MCP服务器。请注意将 '/full/path/to/todoist_server.py' 替换为 'todoist_server.py' 脚本的实际绝对路径。

{
  "mcpServers": {
    "todoist-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "todoist_api_python",
        "mcp",
        "run",
        "/full/path/to/todoist_server.py"
      ],
      "env": {
        "TODOIST_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

配置参数说明:

'server name': 服务器名称，例如 "todoist-server"，客户端用此名称引用服务器。
'command': 启动服务器的命令，这里使用 'uv' 运行 Python 脚本。
'args': 传递给 'command' 的参数列表：
- '"run"': 'uv run' 命令用于运行 Python 程序。
- '"--with"': 指定需要包含的依赖项。
- '"mcp[cli]"': 包含 MCP 命令行工具和相关依赖。
- '"--with"': 再次指定依赖项。
- '"todoist_api_python"': 包含 Todoist API Python 客户端库。
- '"mcp"': 调用 'mcp' 命令。
- '"run"': 'mcp run' 子命令用于运行 MCP 服务器。
- '"/full/path/to/todoist_server.py"': MCP 服务器脚本的绝对路径。 请务必替换为实际路径。
'env': 环境变量配置：
- '"TODOIST_API_TOKEN"': Todoist API Token，请务必替换为您的实际 API Token。

基本使用方法

启动服务器 在终端中，导航到仓库目录，并确保已设置 'TODOIST_API_TOKEN' 环境变量。然后运行服务器：
```
python todoist_mcp_server.py
```
服务器将通过标准输入/输出 (stdio) 与 MCP 客户端通信。
通过 MCP 客户端与 Todoist 交互 配置并启动 MCP 客户端（如Claude），客户端将加载上面配置的 'todoist-server'。之后，您可以使用自然语言指示客户端调用 Todoist 工具，例如：
- "添加一个任务：购买杂货" (对应 'todoist_create_task' 工具)
- "显示我所有紧急的任务" (对应 'get_tasks' 工具，并设置优先级过滤条件)
- "完成 ‘洗衣服’ 任务" (对应 'complete_task' 工具，需要提供任务ID或名称进行查找)
具体可参考仓库 'README.md' 中 "Example Interactions" 部分的示例。

注意: 请确保 Todoist API Token 的安全性，不要泄露给他人。

关键词