Todoist MCP

Todoist MCP Server

Bibliothek zum Verbinden von KI-Agenten mit Todoist. Enthält Tools, die in LLMs integriert werden können, sodass diese im Namen des Benutzers auf ein Todoist-Konto zugreifen und es ändern können.

Diese Tools können sowohl über einen MCP-Server verwendet als auch direkt in andere Projekte importiert werden, um sie in Ihre eigenen KI-Konversationsschnittstellen zu integrieren.

Verwenden der Tools

1. Dieses Repository als Abhängigkeit hinzufügen

npm install @doist/todoist-mcp

2. Die Tools importieren und an eine KI anbinden

Hier ist ein Beispiel mit Vercels 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),
    },
})

Verwendung als MCP-Server

Schnellstart

Sie können den MCP-Server direkt mit npx ausführen:

npx @doist/todoist-mcp

Einrichtungsanleitung

Der Todoist-MCP-Server ist als Streamable-HTTP-Dienst für die einfache Integration in verschiedene KI-Clients verfügbar:

Primäre URL (Streamable HTTP): https://ai.todoist.net/mcp

Claude Desktop

1. Öffnen Sie Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen
2. Geben Sie https://ai.todoist.net/mcp ein und schließen Sie die OAuth-Authentifizierung ab

Cursor

Erstellen Sie eine Konfigurationsdatei:

• Global: ~/.cursor/mcp.json
• Projektspezifisch: .cursor/mcp.json

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

Aktivieren Sie dann den Server in den Cursor-Einstellungen, wenn Sie dazu aufgefordert werden.

Claude Code (CLI)

Die schnellste Einrichtung ist das offizielle Todoist-Plugin, das den MCP-Server für Sie einrichtet:

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

OAuth wird beim ersten Verwenden eines Todoist-Tools in Ihrem Browser ausgeführt. Weitere Informationen finden Sie in Anthropics Plugin-Dokumentation.

Wenn Sie den MCP-Server lieber manuell konfigurieren möchten, führen Sie Folgendes aus:

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

Starten Sie dann claude, führen Sie /mcp aus und wählen Sie den todoist-MCP-Server zur Authentifizierung aus.

Visual Studio Code

1. Öffnen Sie die Befehlspalette → MCP: Server hinzufügen
2. Wählen Sie HTTP-Transport und verwenden Sie:

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

Andere MCP-Clients

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

Weitere Details zur Einrichtung und Verwendung des MCP-Servers, einschließlich der Erstellung benutzerdefinierter Server, finden Sie unter docs/mcp-server.md.

Funktionen

Ein Hauptmerkmal dieses Projekts ist, dass Tools wiederverwendet werden können und nicht speziell für die Verwendung in einem MCP-Server geschrieben sind. Sie können als Tools an andere KI-Konversationsschnittstellen (z. B. Vercels AI SDK) angebunden werden.

Dieses Projekt befindet sich in einem frühen Stadium. Erwarten Sie bald weitere und/oder bessere Tools.

Unser Ziel ist es dennoch, eine kleine Reihe von Tools bereitzustellen, die vollständige Workflows ermöglichen, anstatt nur atomare Aktionen, und dabei eine Balance zwischen Flexibilität und Effizienz für LLMs zu schaffen.

Unsere Designphilosophie, Richtlinien und Entwicklungsmuster finden Sie unter docs/tool-design.md.

Verfügbare Tools

Eine vollständige Liste der verfügbaren Tools finden Sie im Verzeichnis src/tools.

OpenAI-MCP-Kompatibilität

Dieser Server enthält search- und fetch-Tools, die der OpenAI-MCP-Spezifikation folgen und eine nahtlose Integration mit dem MCP-Protokoll von OpenAI ermöglichen. Diese Tools geben JSON-kodierte Ergebnisse zurück, die für die Anforderungen von OpenAI optimiert sind, während die Kompatibilität mit dem breiteren MCP-Ökosystem erhalten bleibt.

Abhängigkeiten

• MCP-Server mit dem offiziellen @modelcontextprotocol/server
• Todoist-TypeScript-API-Client @doist/todoist-sdk

MCP-Server-Einrichtung

Vollständige Anweisungen zur Einrichtung des MCP-Servers finden Sie unter docs/mcp-server.md.

Lokale Entwicklungseinrichtung

Vollständige Einrichtungsanweisungen finden Sie unter docs/dev-setup.md und Workflows für Mitwirkende sowie Qualitätsprüfungen unter CONTRIBUTING.md.

MCP Apps

Dieses Projekt unterstützt MCP Apps – interaktive UI-Widgets, die inline in KI-Chat-Oberflächen gerendert werden. Widgets bieten reichhaltige visuelle Darstellungen von Tool-Ausgaben (z. B. Aufgabenlisten) anstelle von reinem Text.

Die Widget-Architektur, Build-Pipeline und der Entwicklungsworkflow finden Sie unter docs/mcp-apps.md.

Schnellstart

Nach dem Klonen und Einrichten des Repositorys:

• npm start - MCP-Inspektor für Tests erstellen und ausführen
• npm run dev - Entwicklungsmodus mit automatischem Neubauen und Neustart
• npm run tool:list - Verfügbare Tools für die direkte Ausführung auflisten
• npm run tool -- <tool-name> '<json-args>' - Ein Tool direkt ohne MCP ausführen

Wenn Sie npm run tool verwenden, fügen Sie -- vor den Tool-Argumenten ein, damit npm sie an scripts/run-tool.ts weiterleitet.

Beispielprüfung vor Schreiboperationen: npm run tool -- user-info '{}' Dies bestätigt, mit welchem Todoist-Konto das aktuelle TODOIST_API_KEY verbunden ist.

run-tool verwendet TODOIST_API_KEY aus Ihrer .env-Datei (erstellt aus .env.example durch npm run setup). Verwenden Sie bei Schreiboperationen ein Testkonto oder ein temporäres Projekt, um die Änderung echter Daten zu vermeiden.

Mitwirken

Siehe CONTRIBUTING.md für:

• Entwicklungsworkflow
• Direktes Ausführen von Tools mit scripts/run-tool.ts
• Tests und Qualitätsprüfungen
• Commit-Konventionen

Veröffentlichung

Dieses Projekt verwendet release-please zur Automatisierung der Versionsverwaltung und Paketveröffentlichung.

So funktioniert es

1. Nehmen Sie Ihre Änderungen mit Conventional Commits vor:

   • feat: für neue Funktionen (Minor-Versionssprung)
   • fix: für Fehlerbehebungen (Patch-Versionssprung)
   • feat!: oder fix!: für bahnbrechende Änderungen (Major-Versionssprung)
   • docs: für Dokumentationsänderungen
   • chore: für Wartungsaufgaben
   • ci: für CI-Änderungen

2. Wenn Commits an main gepusht werden:

   • Release-please erstellt/aktualisiert automatisch einen Release-PR
   • Der PR enthält Versionssprung und Changelog-Aktualisierungen
   • Überprüfen Sie den PR und führen Sie den Merge durch, wenn er bereit ist

3. Nach dem Mergen des Release-PRs:

   • Ein neues GitHub-Release wird automatisch erstellt
   • Ein neues Tag wird erstellt
   • Der publish-Workflow wird ausgelöst
   • Das Paket wird auf npm veröffentlicht