Todoist MCP

官方

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

你可以用 Todoist MCP 做什麼？

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

託管 MCP 伺服器

npx add-mcp 'https://ai.todoist.net/mcp'

可安裝到 Claude Code、Codex、Cursor 等客戶端

文件

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