py todoist mcp
用于Todoist集成的Python MCP（模型上下文协议）服务器，使AI助手能够通过模型上下文协议管理任务和项目。
特性
- 任务管理：创建、读取、更新、完成和删除任务
- 项目管理：管理Todoist项目，支持嵌套项目
- 过滤器支架：使用Todoist强大的筛选器语法查询任务
- 错误处理：通过用户友好的消息进行强大的错误处理
- 结构化日志记录：用于调试和监控的全面日志记录
先决条件
- Python 3.13或更高版本
- 紫外线 用于Python包管理
- Todoist API令牌
安装
1.用uv安装
uv tool install git+https://github.com/chris-jelly/py-todoist-mcp.git这将安装 todoist-mcp 进入一个孤立的环境，并在您的 PATH.
2.设置您的API令牌
服务器读取 TODOIST_API_TOKEN 从环境。将其添加到您的shell配置文件中(~/.bashrc, ~/.zshrc等等）：
# Add to your shell profile
export TODOIST_API_TOKEN="your-api-token-here"获取Todoist API代币：
- 登录到 简洁日程
- 转到“设置”→ 集成→ 开发者
- 复制您的API令牌
注： 避免将API令牌直接放在MCP配置文件中。这些文件很容易被意外提交或共享。服务器将自动从您的环境中获取令牌。
配置
开源代码
添加以下内容 ~/.config/opencode/opencode.json。这使用 uvx 直接从git repo运行服务器——不需要本地安装：
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"todoist": {
"type": "local",
"command": ["uvx", "--from", "git+https://github.com/chris-jelly/py-todoist-mcp.git", "todoist-mcp"],
"environment": {
"TODOIST_API_TOKEN": "{env:TODOIST_API_TOKEN}"
}
}
}
}如果您已经在本地安装了该软件包（通过 uv tool install)，您可以使用更简单的形式：
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"todoist": {
"type": "local",
"command": ["todoist-mcp"]
}
}
}法典
将以下内容添加到Codex配置文件中（位置因安装而异）：
{
"mcpServers": {
"todoist": {
"command": "todoist-mcp"
}
}
}用法
配置后，您可以使用自然语言与Todoist交互：
任务示例
"Show me all my tasks"
"List my tasks for today"
"Create a task 'Buy groceries' due tomorrow with priority 1"
"Get details for task ID 123456"
"Update task 123456 to be due next Monday"
"Mark task 123456 as complete"
"Delete task 123456"项目范例
"List all my projects"
"Create a new project called 'Work'"
"Get details for project ID 987654"
"Update project 987654 color to blue"
"Delete project 987654"筛选器示例
"Show me overdue tasks"
"List tasks in project work"
"Get tasks labeled urgent"可用工具
任务工具
| 工具 | 说明 |
|---|---|
todoist_get_tasks | 列出带有可选筛选器（project_id、filter_string）的任务 |
todoist_get_task | 按ID获取包含完整详细信息的单个任务 |
todoist_add_task | 使用内容、描述、due_date、优先级、project_id、标签创建新任务 |
todoist_update_task | 按ID更新任务属性 |
todoist_complete_task | 按ID将任务标记为已完成 |
todoist_delete_task | 按ID删除任务 |
项目工具
| 工具 | 说明 |
|---|---|
todoist_get_projects | 列出所有项目 |
todoist_get_project | 按ID获取包含完整详细信息的单个项目 |
todoist_add_project | 使用名称、颜色和parent_id创建新项目 |
todoist_update_project | 按ID更新项目属性 |
todoist_delete_project | 按ID删除项目 |
发展
设置
git clone git@github.com:chris-jelly/py-todoist-mcp.git
cd py-todoist-mcp
uv sync在本地运行服务器
uv run todoist-mcp代码质量
此项目使用 拉夫 用于修剪和格式化：
# Format code
ruff format .
# Check for linting errors
ruff check .
# Fix auto-fixable issues
ruff check . --fix项目结构
py-todoist-mcp/
├── src/todoist_mcp/
│ ├── __init__.py
│ ├── main.py # Entry point
│ ├── server.py # FastMCP server setup
│ ├── client.py # Todoist API client
│ ├── utils.py # Logging and error handling
│ └── tools/
│ ├── __init__.py
│ ├── tasks.py # Task management tools
│ └── projects.py # Project management tools
├── pyproject.toml
└── README.md许可证
MIT许可证-有关详细信息，请参阅许可证文件。
贡献
欢迎投稿！请确保：
- 所有代码通过
ruff lint和ruff format检查 - 遵循现有的代码模式和约定
- 添加新功能的测试
- 根据需要更新文档
故障排除
服务器无法启动
- 验证
TODOIST_API_TOKEN设置正确 - 检查是否安装了Python 3.13+：
python --version - 确保安装了紫外线：
uv --version
身份验证错误
- 验证您的API令牌是否正确且尚未过期
- 检查您的Todoist帐户是否处于活动状态
- 确保令牌具有适当的权限
AI助手未连接
对于Opencode：
- 验证配置JSON语法
- 检查Opencode日志：
~/.config/opencode/logs/ - 跑
opencode --version以确保其安装正确 - 配置更改后重新启动Opencode
对于食品法典委员会：
- 验证配置JSON语法
- 检查Codex输出是否有错误消息
- 配置更改后重新启动Codex