Todoist MCP

Serveur Todoist MCP

Bibliothèque pour connecter des agents IA à Todoist. Inclut des outils pouvant être intégrés aux LLM, leur permettant d'accéder à un compte Todoist et de le modifier au nom de l'utilisateur.

Ces outils peuvent être utilisés via un serveur MCP, ou importés directement dans d'autres projets pour les intégrer à vos propres interfaces conversationnelles IA.

Utilisation des outils

1. Ajouter ce dépôt comme dépendance

npm install @doist/todoist-mcp

2. Importer les outils et les connecter à une IA

Voici un exemple utilisant le SDK IA de Vercel.

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),
    },
})

Utilisation comme serveur MCP

Démarrage rapide

Vous pouvez exécuter le serveur MCP directement avec npx :

npx @doist/todoist-mcp

Guide de configuration

Le serveur Todoist MCP est disponible en tant que service HTTP streamable pour une intégration facile avec divers clients IA :

URL principale (HTTP streamable) : https://ai.todoist.net/mcp

Claude Desktop

1. Ouvrez Paramètres → Connecteurs → Ajouter un connecteur personnalisé
2. Saisissez https://ai.todoist.net/mcp et complétez l'authentification OAuth

Cursor

Créez un fichier de configuration :

• Global : ~/.cursor/mcp.json
• Spécifique au projet : .cursor/mcp.json

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

Ensuite, activez le serveur dans les paramètres de Cursor si vous y êtes invité.

Claude Code (CLI)

La configuration la plus rapide est le plugin officiel Todoist, qui configure le serveur MCP pour vous :

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

OAuth s'exécute dans votre navigateur la première fois que vous utilisez un outil Todoist. Consultez la documentation du plugin d'Anthropic pour plus d'informations.

Si vous préférez configurer le serveur MCP manuellement, exécutez :

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

Ensuite, lancez claude, exécutez /mcp, et sélectionnez le serveur MCP todoist pour vous authentifier.

Visual Studio Code

1. Ouvrez la Palette de commandes → MCP : Ajouter un serveur
2. Sélectionnez le transport HTTP et utilisez :

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

Autres clients MCP

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

Pour plus de détails sur la configuration et l'utilisation du serveur MCP, y compris la création de serveurs personnalisés, consultez docs/mcp-server.md.

Fonctionnalités

Une caractéristique clé de ce projet est que les outils peuvent être réutilisés et ne sont pas écrits spécifiquement pour une utilisation dans un serveur MCP. Ils peuvent être connectés comme outils à d'autres interfaces conversationnelles IA (par exemple, le SDK IA de Vercel).

Ce projet en est à ses débuts. Attendez-vous à davantage et/ou de meilleurs outils bientôt.

Néanmoins, notre objectif est de fournir un petit ensemble d'outils permettant des flux de travail complets, plutôt que de simples actions atomiques, en trouvant un équilibre entre flexibilité et efficacité pour les LLM.

Pour notre philosophie de conception, nos directives et nos modèles de développement, consultez docs/tool-design.md.

Outils disponibles

Pour une liste complète des outils disponibles, consultez le répertoire src/tools.

Compatibilité MCP OpenAI

Ce serveur inclut les outils search et fetch qui suivent la spécification MCP OpenAI, permettant une intégration transparente avec le protocole MCP d'OpenAI. Ces outils renvoient des résultats encodés en JSON optimisés pour les exigences d'OpenAI tout en maintenant la compatibilité avec l'écosystème MCP plus large.

Dépendances

• Serveur MCP utilisant le @modelcontextprotocol/server officiel
• Client API Typescript Todoist @doist/todoist-sdk

Configuration du serveur MCP

Consultez docs/mcp-server.md pour les instructions complètes sur la configuration du serveur MCP.

Configuration du développement local

Consultez docs/dev-setup.md pour les instructions complètes de configuration et CONTRIBUTING.md pour les flux de travail des contributeurs et les contrôles de qualité.

Applications MCP

Ce projet inclut la prise en charge des applications MCP – des widgets d'interface utilisateur interactifs rendus en ligne dans les interfaces de chat IA. Les widgets fournissent des représentations visuelles riches des sorties d'outils (par exemple, des listes de tâches) au lieu de texte brut.

Consultez docs/mcp-apps.md pour l'architecture des widgets, le pipeline de construction et le flux de travail de développement.

Démarrage rapide

Après avoir cloné et configuré le dépôt :

• npm start - Construire et exécuter l'inspecteur MCP pour les tests
• npm run dev - Mode développement avec reconstruction et redémarrage automatiques
• npm run tool:list - Lister les outils disponibles pour une exécution directe
• npm run tool -- <tool-name> '<json-args>' - Exécuter un outil directement sans MCP

Lorsque vous utilisez npm run tool, incluez -- avant les arguments de l'outil afin que npm les transmette à scripts/run-tool.ts.

Exemple de vérification avant les opérations d'écriture : npm run tool -- user-info '{}' Cela confirme à quel compte Todoist le TODOIST_API_KEY actuel est connecté.

run-tool utilise TODOIST_API_KEY de votre fichier .env (créé à partir de .env.example par npm run setup). Utilisez un compte de test ou un projet temporaire lors des opérations d'écriture pour éviter de modifier des données réelles.

Contribution

Consultez CONTRIBUTING.md pour :

• Le flux de travail de développement
• L'exécution directe des outils avec scripts/run-tool.ts
• Les tests et les contrôles de qualité
• Les conventions de commit

Publication

Ce projet utilise release-please pour automatiser la gestion des versions et la publication des packages.

Comment cela fonctionne

1. Effectuez vos modifications en utilisant les Commits conventionnels :

   • feat: pour les nouvelles fonctionnalités (incrémentation de version mineure)
   • fix: pour les corrections de bugs (incrémentation de version de correctif)
   • feat!: ou fix!: pour les changements cassants (incrémentation de version majeure)
   • docs: pour les modifications de documentation
   • chore: pour les tâches de maintenance
   • ci: pour les modifications CI

2. Lorsque les commits sont poussés vers main :

   • Release-please crée/met à jour automatiquement une PR de publication
   • La PR inclut l'incrémentation de version et les mises à jour du journal des modifications
   • Examinez la PR et fusionnez-la lorsqu'elle est prête

3. Après la fusion de la PR de publication :

   • Une nouvelle version GitHub est automatiquement créée
   • Un nouveau tag est créé
   • Le workflow publish est déclenché
   • Le package est publié sur npm