AI导哈

任务管理服务器

一个与Todoist无缝集成的MCP服务器，使AI助手能够通过Todoist API管理任务和项目。

  • by 5uh417
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 5uh417/todoist-mcp-server

使用说明

Todoist MCP服务器

模型上下文协议（MCP）服务器，提供与Todoist的无缝集成，使人工智能助手能够通过Todoist API管理任务和项目。

特性

🔧 核心工具

  • 任务管理

    • get_tasks -从Todoist检索任务（可选项目筛选）
    • create_task -创建具有完全自定义功能的新任务（优先级、标签、截止日期）
    • complete_task -将任务标记为已完成

  • 项目管理

    • get_projects -从您的Todoist帐户检索所有项目
    • create_project -使用可选的颜色自定义创建新项目

  • 设置和配置

    • setup_todoist -动态API令牌配置和连接验证

🏗️ 建筑

  • FastMCP框架：基于现代FastMCP服务器框架构建，实现最佳性能
  • 异步操作：对非阻塞API调用的完全异步/等待支持
  • 模块化设计：通过专用模块将关注点彻底分离，用于：
    • 任务操作(src/tools/tasks.py)
    • 项目运营(src/tools/projects.py)
    • API客户端(src/todoist_client.py)
    • 资源管理(src/resources/)
    • 及时管理(src/prompts/)

🔐 安全与配置

  • 环境变量：通过安全的API令牌管理 .env 文件
  • 令牌验证：内置连接测试和验证
  • 错误处理：全面的错误处理，带有有意义的错误消息

安装

先决条件

  • Python 3.10或更高版本
  • 具有API访问权限的Todoist帐户

设置

  1. 安装软件包

    pip install -e .

  2. 设置Todoist API代币

    创建一个 .env 项目根目录中的文件：

    TODOIST_API_TOKEN=your_api_token_here

    或者将其设置为环境变量：

    export TODOIST_API_TOKEN=your_api_token_here

  3. 配置Claude桌面 （如果与Claude Desktop一起使用）

    添加到您的 claude_desktop_config.json:

    {
  "mcpServers": {
    "todoist": {
      "url": "http://127.0.0.1:8000",
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

用法

运行服务器

# Direct execution
python main.py

# Or using the module
python -m src.server

HTTP服务器模式

服务器还支持基于web的集成的HTTP模式：

python -m uvicorn src.http_server:app --reload --port 8000

API集成

任务操作

# Get all tasks
tasks = await get_tasks()

# Get tasks from specific project
project_tasks = await get_tasks(project_id="12345")

# Create a new task
task = await create_task(
    content="Review quarterly reports",
    project_id="work_project_id",
    priority=3,
    due_string="tomorrow at 9am",
    labels=["urgent", "review"]
)

# Complete a task
result = await complete_task(task_id="67890")

项目运营

# Get all projects
projects = await get_projects()

# Create a new project
project = await create_project(
    name="Q4 Planning",
    color="blue"
)

发展

项目结构

todoist-mcp-server/
├── src/
│   ├── __main__.py              # Module entry point
│   ├── server.py                # Main MCP server setup
│   ├── http_server.py           # HTTP server variant
│   ├── todoist_client.py        # Todoist API client
│   ├── tools/
│   │   ├── tasks.py            # Task management tools
│   │   └── projects.py         # Project management tools
│   ├── resources/
│   │   └── todoist_resources.py # MCP resources
│   └── prompts/
│       ├── task_prompts.py     # Task-related prompts
│       └── project_prompts.py  # Project-related prompts
├── main.py                      # Simple entry point
├── pyproject.toml              # Project configuration
├── claude_desktop_config.json  # Claude Desktop configuration
└── CLAUDE.md                   # Development guidelines

依赖项

  • mcp[cli] （≥1.4.0）-模型上下文协议框架
  • httpx （≥0.25.0）-用于API调用的现代HTTP客户端
  • 优维康 （≥0.23.0）-ASGI服务器用于HTTP模式
  • python dotenv （≥1.1.1）-环境变量管理

开发命令

# Install in development mode
pip install -e .

# Run with auto-reload (development)
python -m uvicorn src.http_server:app --reload

# Test API connection
python -c "from src.todoist_client import TodoistClient; import asyncio; asyncio.run(TodoistClient().get_projects())"

贡献

本项目遵循清洁建筑原则：

  1. API客户端层 (todoist_client.py)-处理Todoist API的所有交互
  2. 工具层 (tools/)-MCP工具实施
  3. 服务器层 (server.py)-MCP服务器设置和配置
  4. 资源和提示 -MCP资源和及时管理

贡献时：

  • 遵循现有的异步模式
  • 添加适当的错误处理
  • 更新新功能的文档
  • 使用环境变量和动态令牌设置进行测试

许可证

该项目是开源的，可以在标准许可条款下使用。

相关 MCP