Todoist MCP

官方

直接從您的LLM管理Todoist任務和專案。

GitHub

541

試用此 MCP贊助

你可以用 Todoist MCP 做什麼？

按日期尋找任務 — 請您的助理使用 findTasksByDate 尋找特定日期的任務。
新增任務 — 讓您的助理透過 addTasks 工具為您建立一或多個 Todoist 任務。
檢查帳戶身分 — 在進行變更前，使用 user-info 確認目前的使用者，詢問已連線的 Todoist 帳戶。
直接執行工具 — 使用 npm run tool 搭配 JSON 引數獨立執行任何工具，略過 MCP 伺服器。

文件

Todoist MCP 伺服器

用於將 AI 代理連接到 Todoist 的函式庫。包含可整合到 LLM 的工具，使其能夠代表使用者存取和修改 Todoist 帳戶。

這些工具可以透過 MCP 伺服器使用，也可以直接匯入其他專案，整合到您自己的 AI 對話介面中。

使用工具

1. 將此儲存庫新增為依賴項

npm install @doist/todoist-mcp

2. 匯入工具並將其連接到 AI

以下是使用 Vercel 的 AI SDK 的範例。

import { findTasksByDate, addTasks } from '@doist/todoist-mcp'
import { TodoistApi } from '@doist/todoist-sdk'
import { streamText } from 'ai'

// Create Todoist API client
const client = new TodoistApi(process.env.TODOIST_API_KEY)

// Helper to wrap tools with the client
function wrapTool(tool, todoistClient) {
    return {
        ...tool,
        execute(args) {
            return tool.execute(args, todoistClient)
        },
    }
}

const result = streamText({
    model: yourModel,
    system: 'You are a helpful Todoist assistant',
    tools: {
        findTasksByDate: wrapTool(findTasksByDate, client),
        addTasks: wrapTool(addTasks, client),
    },
})

作為 MCP 伺服器使用

快速開始

您可以直接使用 npx 執行 MCP 伺服器：

npx @doist/todoist-mcp

設定指南

Todoist MCP 伺服器以可串流 HTTP 服務的形式提供，方便與各種 AI 用戶端整合：

主要 URL（可串流 HTTP）： https://ai.todoist.net/mcp

Claude Desktop

開啟設定 → 連接器 → 新增自訂連接器
輸入 https://ai.todoist.net/mcp 並完成 OAuth 驗證

Cursor

建立設定檔：

全域： ~/.cursor/mcp.json
專案特定： .cursor/mcp.json

{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]
        }
    }
}

然後在 Cursor 設定中啟用伺服器（如有提示）。

Claude Code（CLI）

最快的設定方式是使用官方 Todoist 外掛程式，它會自動為您設定 MCP 伺服器：

/plugin marketplace add doist/todoist-mcp
/plugin install todoist@doist

當您第一次使用 Todoist 工具時，OAuth 會在您的瀏覽器中執行。更多資訊請參閱 Anthropic 的外掛程式文件。

如果您想手動設定 MCP 伺服器，請執行：

claude mcp add --transport http todoist https://ai.todoist.net/mcp

然後啟動 claude，執行 /mcp，並選擇 todoist MCP 伺服器進行驗證。

Visual Studio Code

開啟命令面板 → MCP：新增伺服器
選擇 HTTP 傳輸並使用：

{
    "servers": {
        "todoist": {
            "type": "http",
            "url": "https://ai.todoist.net/mcp"
        }
    }
}

其他 MCP 用戶端

npx -y mcp-remote https://ai.todoist.net/mcp

有關設定和使用 MCP 伺服器的更多詳細資訊，包括建立自訂伺服器，請參閱 docs/mcp-server.md。

功能

此專案的一個關鍵功能是工具可以重複使用，並非專門為 MCP 伺服器而撰寫。它們可以作為工具連接到其他對話式 AI 介面（例如 Vercel 的 AI SDK）。

此專案仍處於早期階段。預計很快就會新增更多和/或更好的工具。

儘管如此，我們的目標是提供一組小型工具來實現完整的工作流程，而不僅僅是原子操作，在 LLM 的靈活性和效率之間取得平衡。

有關我們的設計理念、指南和開發模式，請參閱 docs/tool-design.md。

可用工具

如需完整的可用工具清單，請參閱 src/tools 目錄。

OpenAI MCP 相容性

此伺服器包含遵循 OpenAI MCP 規範的 search 和 fetch 工具，可與 OpenAI 的 MCP 協定無縫整合。這些工具會傳回針對 OpenAI 需求最佳化的 JSON 編碼結果，同時保持與更廣泛 MCP 生態系統的相容性。

依賴項

使用官方 @modelcontextprotocol/server 的 MCP 伺服器
Todoist Typescript API 用戶端 @doist/todoist-sdk

MCP 伺服器設定

有關設定 MCP 伺服器的完整說明，請參閱 docs/mcp-server.md。

本機開發設定

有關完整的設定說明，請參閱 docs/dev-setup.md，有關貢獻者工作流程和品質檢查，請參閱 CONTRIBUTING.md。

MCP 應用程式

此專案包含對 MCP 應用程式 的支援 – 在 AI 聊天介面中內嵌呈現的互動式 UI 小工具。小工具提供工具輸出的豐富視覺表示（例如任務清單），而不是純文字。

有關小工具架構、建置管線和開發工作流程，請參閱 docs/mcp-apps.md。

快速開始

複製並設定儲存庫後：

npm start - 建置並執行 MCP inspector 進行測試
npm run dev - 開發模式，具備自動重建和重新啟動功能
npm run tool:list - 列出可直接執行的可用工具
npm run tool -- <tool-name> '<json-args>' - 直接執行工具，無需 MCP

使用 npm run tool 時，請在工具參數前加上 --，以便 npm 將其轉發給 scripts/run-tool.ts。

寫入操作前的檢查範例： npm run tool -- user-info '{}' 這會確認目前的 TODOIST_API_KEY 連線到哪個 Todoist 帳戶。

run-tool 使用您 .env 檔案中的 TODOIST_API_KEY（由 npm run setup 從 .env.example 建立）。執行寫入操作時，請使用測試帳戶或臨時專案，以避免修改真實資料。

貢獻

請參閱 CONTRIBUTING.md 了解：

開發工作流程
使用 scripts/run-tool.ts 直接執行工具
測試和品質檢查
提交慣例

發行

此專案使用 release-please 來自動化版本管理和套件發布。

運作方式

使用 Conventional Commits 進行您的變更：
- feat: 用於新功能（次要版本升級）
- fix: 用於錯誤修正（修補程式版本升級）
- feat!: 或 fix!: 用於破壞性變更（主要版本升級）
- docs: 用於文件變更
- chore: 用於維護任務
- ci: 用於 CI 變更
當提交推送到 main 時：
- Release-please 會自動建立/更新發行 PR
- PR 包含版本升級和變更日誌更新
- 審查 PR 並在準備就緒時合併
合併發行 PR 後：
- 會自動建立新的 GitHub 發行版本
- 會建立新的標籤
- 會觸發 publish 工作流程
- 套件會發布到 npm