Todoist MCP

oficial

Gestiona tus tareas y proyectos de Todoist directamente desde tu LLM.

GitHub
541
Prueba este MCPPatrocinado

¿Qué puedes hacer con Todoist MCP?

  • Buscar tareas por fecha — Pídele a tu asistente que localice tareas programadas para un día específico usando findTasksByDate.
  • Agregar nuevas tareas — Haz que tu asistente cree una o más tareas de Todoist para ti mediante la herramienta addTasks.
  • Verificar la identidad de la cuenta — Pregunta qué cuenta de Todoist está conectada antes de hacer cambios, usando user-info para confirmar el usuario activo.
  • Ejecutar herramientas directamente — Usa npm run tool para ejecutar cualquier herramienta de forma independiente con argumentos JSON, omitiendo el servidor MCP.

Documentación

Servidor Todoist MCP

Biblioteca para conectar agentes de IA a Todoist. Incluye herramientas que pueden integrarse en LLMs, permitiéndoles acceder y modificar una cuenta de Todoist en nombre del usuario.

Estas herramientas pueden usarse tanto a través de un servidor MCP, como importarse directamente en otros proyectos para integrarlas en tus propias interfaces conversacionales de IA.

Uso de herramientas

1. Añade este repositorio como dependencia

npm install @doist/todoist-mcp

2. Importa las herramientas y conéctalas a una IA

Aquí tienes un ejemplo usando el SDK de 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),
    },
})

Uso como servidor MCP

Inicio rápido

Puedes ejecutar el servidor MCP directamente con npx:

npx @doist/todoist-mcp

Guía de configuración

El servidor Todoist MCP está disponible como un servicio HTTP transmisible para facilitar la integración con varios clientes de IA:

URL principal (HTTP transmisible): https://ai.todoist.net/mcp

Claude Desktop

  1. Abre Configuración → Conectores → Añadir conector personalizado
  2. Introduce https://ai.todoist.net/mcp y completa la autenticación OAuth

Cursor

Crea un archivo de configuración:

  • Global: ~/.cursor/mcp.json
  • Específico del proyecto: .cursor/mcp.json
{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]
        }
    }
}

Luego habilita el servidor en la configuración de Cursor si se te solicita.

Claude Code (CLI)

La configuración más rápida es el plugin oficial de Todoist, que configura el servidor MCP por ti:

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

OAuth se ejecuta en tu navegador la primera vez que uses una herramienta de Todoist. Consulta la documentación de plugins de Anthropic para más información.

Si prefieres configurar el servidor MCP manualmente, ejecuta:

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

Luego inicia claude, ejecuta /mcp y selecciona el servidor MCP todoist para autenticarte.

Visual Studio Code

  1. Abre la Paleta de Comandos → MCP: Añadir servidor
  2. Selecciona transporte HTTP y usa:
{
    "servers": {
        "todoist": {
            "type": "http",
            "url": "https://ai.todoist.net/mcp"
        }
    }
}

Otros clientes MCP

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

Para más detalles sobre cómo configurar y usar el servidor MCP, incluida la creación de servidores personalizados, consulta docs/mcp-server.md.

Características

Una característica clave de este proyecto es que las herramientas pueden reutilizarse y no están escritas específicamente para usarse en un servidor MCP. Pueden conectarse como herramientas a otras interfaces conversacionales de IA (por ejemplo, el SDK de IA de Vercel).

Este proyecto está en sus primeras etapas. Espera más y/o mejores herramientas pronto.

No obstante, nuestro objetivo es proporcionar un pequeño conjunto de herramientas que permitan flujos de trabajo completos, en lugar de solo acciones atómicas, logrando un equilibrio entre flexibilidad y eficiencia para los LLMs.

Para nuestra filosofía de diseño, pautas y patrones de desarrollo, consulta docs/tool-design.md.

Herramientas disponibles

Para una lista completa de herramientas disponibles, consulta el directorio src/tools.

Compatibilidad MCP de OpenAI

Este servidor incluye las herramientas search y fetch que siguen la especificación MCP de OpenAI, lo que permite una integración perfecta con el protocolo MCP de OpenAI. Estas herramientas devuelven resultados codificados en JSON optimizados para los requisitos de OpenAI, manteniendo al mismo tiempo la compatibilidad con el ecosistema MCP más amplio.

Dependencias

Configuración del servidor MCP

Consulta docs/mcp-server.md para obtener instrucciones completas sobre cómo configurar el servidor MCP.

Configuración de desarrollo local

Consulta docs/dev-setup.md para obtener instrucciones completas de configuración y CONTRIBUTING.md para flujos de trabajo de contribución y controles de calidad.

Aplicaciones MCP

Este proyecto incluye soporte para Aplicaciones MCP: widgets de interfaz de usuario interactivos renderizados en línea en interfaces de chat de IA. Los widgets proporcionan representaciones visuales enriquecidas de las salidas de las herramientas (por ejemplo, listas de tareas) en lugar de texto plano.

Consulta docs/mcp-apps.md para conocer la arquitectura de widgets, el proceso de compilación y el flujo de trabajo de desarrollo.

Inicio rápido

Después de clonar y configurar el repositorio:

  • npm start - Compila y ejecuta el inspector MCP para pruebas
  • npm run dev - Modo de desarrollo con reconstrucción y reinicio automáticos
  • npm run tool:list - Lista las herramientas disponibles para ejecución directa
  • npm run tool -- <tool-name> '<json-args>' - Ejecuta una herramienta directamente sin MCP

Al usar npm run tool, incluye -- antes de los argumentos de la herramienta para que npm los reenvíe a scripts/run-tool.ts.

Ejemplo de verificación antes de operaciones de escritura: npm run tool -- user-info '{}' Esto confirma a qué cuenta de Todoist está conectado el TODOIST_API_KEY actual.

run-tool usa TODOIST_API_KEY de tu archivo .env (creado a partir de .env.example por npm run setup). Usa una cuenta de prueba o un proyecto temporal al ejecutar operaciones de escritura para evitar modificar datos reales.

Contribuciones

Consulta CONTRIBUTING.md para:

  • Flujo de trabajo de desarrollo
  • Ejecución de herramientas directamente con scripts/run-tool.ts
  • Pruebas y controles de calidad
  • Convenciones de commits

Publicación de versiones

Este proyecto usa release-please para automatizar la gestión de versiones y la publicación de paquetes.

Cómo funciona

  1. Haz tus cambios usando Commits Convencionales:

    • feat: para nuevas funciones (incremento de versión menor)
    • fix: para correcciones de errores (incremento de versión de parche)
    • feat!: o fix!: para cambios que rompen compatibilidad (incremento de versión mayor)
    • docs: para cambios de documentación
    • chore: para tareas de mantenimiento
    • ci: para cambios de CI

  2. Cuando se envían commits a main:

    • Release-please crea/actualiza automáticamente un PR de versión
    • El PR incluye el incremento de versión y actualizaciones del registro de cambios
    • Revisa el PR y combínalo cuando esté listo

  3. Después de combinar el PR de versión:

    • Se crea automáticamente una nueva versión de GitHub
    • Se crea una nueva etiqueta
    • Se activa el flujo de trabajo publish
    • El paquete se publica en npm