Todoist MCP Server Ext

🚀 增強版Todoist MCP服務器擴展

這是一個全面的MCP（模型上下文協議）服務器實現，可實現Claude與Todoist的完全集成。此擴展版本由kydycode從原始的@abhiz123/todoist-mcp-server派生而來，並進行了增強，使用完整的Todoist API和最新的MCP SDK（@doist/todoist-api-typescript@4.0.4），增加了額外功能、提高了兼容性並增強了實用性。

擴展版本 - 由kydycode從原始的@abhiz123/todoist-mcp-server派生並增強。

🚀 快速開始

本擴展版本的Todoist MCP服務器可幫助你更好地集成Claude與Todoist，實現高效的任務管理。以下是使用前的準備步驟。

✨ 主要特性

🔧 技術改進

• 更新的Todoist SDK：現在使用@doist/todoist-api-typescript@4.0.4。
• 更新的MCP SDK兼容性：與MCP SDK 0.5.0兼容。
• 增強的錯誤處理：全面的錯誤處理，帶有詳細的錯誤消息。
• 改進的TypeScript支持：更好的類型安全性和兼容性。
• 優化的API使用：高效使用Todoist API，包括用於強大搜索的getTasksByFilter和用於語義任務移動的moveTasks。
• 更好的響應格式：增強了任務、項目和標籤的格式，提高了可讀性，包括在搜索結果中顯示項目名稱。

✨ 增強的任務管理（10個工具）

• 基於ID的直接操作：使用任務ID進行高效的任務操作。
• 全面的任務創建：支持子任務、標籤、項目、部分、優先級。
• 快速添加集成：使用Todoist的快速添加功能進行自然語言任務創建。
• 高級任務搜索：使用Todoist的過濾引擎進行強大的關鍵字搜索（search: 你的查詢）。
• 任務移動功能：在項目、部分之間移動任務，或將其設為子任務。
• 任務狀態管理：完成、重新打開和管理任務生命週期。
• 詳細的任務輸出：搜索和獲取任務操作返回更多任務細節。

🗂️ 完整的項目管理（5個工具）

• 完整的項目CRUD操作：使用所有屬性創建、讀取、更新、刪除項目。
• 子項目支持：創建分層項目結構。
• 項目自定義：設置顏色、收藏、視圖樣式（列表/看板）。
• 增強的項目列表：改進了項目檢索，支持分頁和詳細格式。

📋 部分管理（4個工具）

• 完整的部分操作：創建、讀取、更新、刪除部分。
• 特定項目的部分：過濾和管理項目內的部分。
• 部分組織：正確的排序和結構管理。

🏷️ 標籤管理（5個工具）

• 完整的標籤CRUD操作：創建、讀取、更新、刪除標籤。
• 標籤自定義：設置名稱、顏色、收藏、順序。
• 分頁標籤列表：高效檢索所有標籤。

💬 評論管理（5個工具）

• 完整的評論CRUD操作：在任務和項目上創建、讀取、更新、刪除評論。
• 附件支持：在評論中添加帶有元數據的文件附件。
• 靈活的目標設置：評論可以附加到任務或項目上。
• 分頁評論檢索：高效瀏覽評論線程。

📦 安裝指南

本地開發設置

# 克隆擴展版本的倉庫
git clone https://github.com/kydycode/todoist-mcp-server-ext.git
cd todoist-mcp-server-ext

# 安裝依賴
npm install

# 構建項目
npm run build

獲取Todoist API令牌

1. 登錄你的Todoist賬戶。
2. 導航到設置 → 集成 → 開發者。
3. 複製你的API令牌。

在Claude Desktop中使用

添加到你的claude_desktop_config.json文件中：

選項1：運行本地構建版本

{
  "mcpServers": {
    "todoist-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/todoist-mcp-server-ext/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "你的API令牌"
      }
    }
  }
}

選項2：通過npm/npx運行（推薦用於發佈版本）

{
  "mcpServers": {
    "todoist-mcp-server": {
      "command": "npx",
      "args": ["-y", "@kydycode/todoist-mcp-server-ext@latest"],
      "env": {
        "TODOIST_API_TOKEN": "你的API令牌"
      }
    }
  }
}

選項3：先全局安裝

# 全局安裝擴展版本
npm install -g @kydycode/todoist-mcp-server-ext@latest

# 然後在Claude Desktop配置中使用
{
  "mcpServers": {
    "todoist-mcp-server": {
      "command": "todoist-mcp-server-ext",
      "env": {
        "TODOIST_API_TOKEN": "你的API令牌"
      }
    }
  }
}

💻 使用示例

🎯 高級任務創建與管理

"創建任務 '團隊會議 @明天 #工作 p1'"
"添加任務 '修復關鍵漏洞 +KydyCode @開發項目 L:緊急 L:後端'"
"快速添加: '明天下午2點買牛奶 #購物 !p1'"
"將ID為 {task_id} 的任務移動到項目 {project_id}"
"搜索任務: search: API部署"

🗂️ 項目、部分、標籤和評論管理

"列出我所有的項目"
"創建項目 '第二季度規劃' 顏色:藍色 收藏:true 視圖:看板"
"獲取項目 {project_id} 的部分"
"創建標籤 '高優先級' 顏色:紅色 收藏:true"
"列出所有標籤"
"給任務 {task_id} 添加評論 '這項任務進展順利！'"
"獲取項目 {project_id} 的所有評論"
"用新內容更新評論 {comment_id}"

🆚 擴展版與原版對比

🔧 技術細節

項目結構

src/
├── index.ts          # 包含所有工具的主服務器實現
package.json      # 依賴項和腳本
tsconfig.json     # TypeScript配置
README.md         # 本文件
local-instructions.md # 個人發佈指南
LICENSE
.gitignore
dist/             # 編譯後的JavaScript輸出（在 `npm run build` 之後）
    ├── index.js
    └── index.d.ts

從源代碼構建

# 安裝依賴
npm install

# 構建TypeScript
npm run build

# 測試服務器（需要TODOIST_API_TOKEN）
# 示例：設置令牌併發送列出工具的請求
export TODOIST_API_TOKEN="你的實際Todoist API令牌"
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | node dist/index.js

開發腳本

npm run build     # 編譯TypeScript並使輸出可執行
npm run watch     # 監視更改並重新構建（不使輸出可執行）
npm run prepare   # 發佈前構建（運行build）

🤝 貢獻

歡迎貢獻代碼！此擴展版本接受以下方面的貢獻：

• 額外的Todoist API端點
• 增強的錯誤處理和驗證
• 性能優化
• 文檔改進
• 錯誤修復和兼容性更新

請將問題和拉取請求提交到擴展版本倉庫。

📄 許可證

本項目採用MIT許可證 - 詳情請參閱LICENSE文件。

🙏 致謝

• 擴展版本：kydycode - 增強了功能和兼容性
• 原始創建者：@abhiz123 - 初始的Todoist MCP服務器實現
• MCP協議：模型上下文協議 由Anthropic提供

🐛 問題與支持

• 擴展版本問題：GitHub問題
• 原始倉庫：abhiz123/todoist-mcp-server

🔗 相關鏈接

• 擴展版本倉庫：kydycode/todoist-mcp-server-ext
• NPM包：@kydycode/todoist-mcp-server-ext
• 原始倉庫：abhiz123/todoist-mcp-server
• Todoist API文檔
• 模型上下文協議
• Claude Desktop