Microsoft To Do MCP

Interactúa con Microsoft To Do usando la API de Microsoft Graph.

Documentación

Microsoft To Do MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a asistentes de IA como Claude y Cursor interactuar con Microsoft To Do a través de la API de Microsoft Graph. Este servicio proporciona capacidades integrales de gestión de tareas mediante un flujo de autenticación OAuth 2.0 seguro.

Características

15 Herramientas MCP: Funcionalidad completa de gestión de tareas, incluyendo listas, tareas, elementos de lista de verificación y funciones de organización
Autenticación sin interrupciones: Renovación automática de tokens sin intervención manual
Autenticación OAuth 2.0: Autenticación segura con renovación automática de tokens
Integración con la API de Microsoft Graph: Integración directa con la API oficial de Microsoft
Soporte multiinquilino: Funciona con cuentas personales, laborales y escolares de Microsoft
TypeScript: Completamente tipado para mayor fiabilidad y experiencia de desarrollo
Módulos ESM: Sistema moderno de módulos de JavaScript

Requisitos previos

Node.js 16 o superior (probado con Node.js 18.x, 20.x y 22.x)
Gestor de paquetes pnpm
Una cuenta de Microsoft (personal, laboral o escolar)
Registro de aplicación en Azure (ver configuración a continuación)

Instalación

Opción 1: Instalación global (recomendada)

# Install globally using npm
npm install -g microsoft-todo-mcp-server

# Or using pnpm
pnpm install -g microsoft-todo-mcp-server

# Or run directly with npx (no installation)
npx microsoft-todo-mcp-server

El paquete proporciona tres alias de comando:

microsoft-todo-mcp-server - Nombre completo del paquete
mstodo - Alias corto para el servidor MCP
mstodo-config - Herramienta auxiliar de configuración

Opción 2: Clonar y ejecutar localmente

git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
pnpm install
pnpm run build

Registro de aplicación en Azure

Vaya al Portal de Azure
Navegue a "Registros de aplicaciones" y cree un nuevo registro
Asigne un nombre a su aplicación (por ejemplo, "To Do MCP")
Para "Tipos de cuenta admitidos", seleccione una de las siguientes opciones según sus necesidades:
- Solo cuentas de este directorio organizativo (inquilino único) - Para uso dentro de una sola organización
- Cuentas de cualquier directorio organizativo (cualquier directorio de Azure AD - multiinquilino) - Para uso en múltiples organizaciones
- Cuentas de cualquier directorio organizativo y cuentas personales de Microsoft - Para cuentas laborales y personales
Establezca la URI de redirección en http://localhost:3000/callback
Después de crear la aplicación, vaya a "Certificados y secretos" y cree un nuevo secreto de cliente
Vaya a "Permisos de API" y agregue los siguientes permisos:
- Microsoft Graph > Permisos delegados:
  - Tasks.Read
  - Tasks.ReadWrite
  - User.Read
Haga clic en "Conceder consentimiento de administrador" para estos permisos

Configuración

Configuración del entorno

Cree un archivo .env en la raíz del proyecto (requerido para la autenticación):

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
TENANT_ID=your_tenant_setting
REDIRECT_URI=http://localhost:3000/callback

Opciones de TENANT_ID

organizations - Para cuentas organizativas multiinquilino (predeterminado si no se especifica)
consumers - Solo para cuentas personales de Microsoft
common - Para cuentas organizativas y personales
your-specific-tenant-id - Para configuraciones de inquilino único

Ejemplos:

# For multi-tenant organizational accounts (default)
TENANT_ID=organizations

# For personal Microsoft accounts
TENANT_ID=consumers

# For both organizational and personal accounts
TENANT_ID=common

# For a specific organization tenant
TENANT_ID=00000000-0000-0000-0000-000000000000

Almacenamiento de tokens

El servidor almacena los tokens de autenticación en tokens.json con renovación automática 5 minutos antes de la expiración. Puede sobrescribir la ubicación del archivo de tokens:

# Using environment variable
export MSTODO_TOKEN_FILE=/path/to/custom/tokens.json

# Or pass tokens directly
export MS_TODO_ACCESS_TOKEN=your_access_token
export MS_TODO_REFRESH_TOKEN=your_refresh_token

Uso

Flujo de trabajo de configuración completo

Paso 1: Autenticarse con Microsoft

# If installed globally
git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
pnpm install
pnpm run auth

# Or if running locally
pnpm run auth

Esto abre una ventana del navegador para la autenticación de Microsoft y crea un archivo tokens.json.

Paso 2: Crear la configuración de MCP

# Generate MCP configuration file
pnpm run create-config

# Or use the global helper (if installed globally)
mstodo-config

Esto crea un archivo mcp.json con sus tokens de autenticación.

Paso 3: Configurar su asistente de IA

Para Claude Desktop:

Agregue a su archivo de configuración:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "microsoftTodo": {
      "command": "npx",
      "args": ["--yes", "microsoft-todo-mcp-server"],
      "env": {
        "MS_TODO_ACCESS_TOKEN": "your_access_token",
        "MS_TODO_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Para Cursor:

# Copy to Cursor's global configuration
cp mcp.json ~/.cursor/mcp-servers.json

Scripts disponibles

# Development & Building
pnpm run build        # Build TypeScript to JavaScript
pnpm run dev          # Build and run CLI in one command

# Running the Server
pnpm start            # Run MCP server directly
pnpm run cli          # Run MCP server via CLI wrapper
npx microsoft-todo-mcp-server  # Run globally installed version

# Authentication & Configuration
pnpm run auth         # Start OAuth authentication server
pnpm run create-config # Generate mcp.json from tokens.json

# Code Quality
pnpm run format       # Format code with Prettier
pnpm run format:check # Check code formatting
pnpm run lint         # Run linting checks
pnpm run typecheck    # TypeScript type checking

Herramientas MCP

El servidor proporciona 13 herramientas para la gestión integral de Microsoft To Do:

Autenticación

auth-status - Verificar el estado de autenticación, la expiración del token y el tipo de cuenta

Listas de tareas (contenedores de nivel superior)

get-task-lists - Recuperar todas las listas de tareas con metadatos (predeterminada, compartida, etc.)
create-task-list - Crear una nueva lista de tareas
update-task-list - Renombrar una lista de tareas existente
delete-task-list - Eliminar una lista de tareas y todo su contenido

Tareas (elementos principales de pendientes)

get-tasks - Obtener tareas de una lista con filtrado, ordenación y paginación
- Admite parámetros de consulta OData: $filter, $select, $orderby, $top, $skip, $count
create-task - Crear una nueva tarea con soporte completo de propiedades
- Título, descripción, fecha de vencimiento, fecha de inicio, importancia, recordatorios, estado, categorías
update-task - Actualizar cualquier propiedad de la tarea
delete-task - Eliminar una tarea y todos sus elementos de lista de verificación

Elementos de lista de verificación (subtareas)

get-checklist-items - Obtener subtareas de una tarea específica
create-checklist-item - Agregar una nueva subtarea a una tarea
update-checklist-item - Actualizar el texto o el estado de finalización de una subtarea
delete-checklist-item - Eliminar una subtarea específica

Arquitectura

Estructura del proyecto

Servidor MCP (src/todo-index.ts) - Servidor principal que implementa el protocolo MCP
Envoltorio CLI (src/cli.ts) - Punto de entrada ejecutable con gestión de tokens
Servidor de autenticación (src/auth-server.ts) - Servidor Express para el flujo OAuth 2.0
Generador de configuración (src/create-mcp-config.ts) - Ayudante para crear configuraciones MCP

Detalles técnicos

API de Microsoft Graph: Utiliza puntos finales v1.0
Autenticación: MSAL (Biblioteca de autenticación de Microsoft) con flujo PKCE
Gestión de tokens: Renovación automática 5 minutos antes de la expiración
Sistema de compilación: ts-builds (tsdown) para compilación rápida de TypeScript
Sistema de módulos: ESM (módulos ECMAScript)

Limitaciones y problemas conocidos

Cuentas personales de Microsoft

Error MailboxNotEnabledForRESTAPI: Las cuentas personales de Microsoft (outlook.com, hotmail.com, live.com) tienen acceso limitado a la API de To Do a través de Microsoft Graph
Esta es una limitación del servicio de Microsoft, no un problema de esta aplicación
Las cuentas laborales/escolares tienen acceso completo a la API

Limitaciones de la API

Se aplican límites de velocidad según las políticas de Microsoft
Algunas funciones pueden no estar disponibles para cuentas personales
Las listas compartidas tienen funcionalidad limitada

Solución de problemas

Problemas de autenticación

Errores de adquisición de tokens

Verifique CLIENT_ID, CLIENT_SECRET y TENANT_ID en su archivo .env
Asegúrese de que la URI de redirección coincida exactamente: http://localhost:3000/callback
Verifique que los permisos de la aplicación de Azure se hayan otorgado con consentimiento de administrador

Problemas de permisos

Asegúrese de que todos los permisos requeridos de Graph API se hayan agregado y consentido
Para cuentas organizativas, puede ser necesario el consentimiento del administrador

Configuración del tipo de cuenta

Cuentas laborales/escolares

TENANT_ID=organizations  # Multi-tenant
# Or use your specific tenant ID

Cuentas personales

TENANT_ID=consumers  # Personal only
# Or TENANT_ID=common for both types

Depuración

Verificar el estado de autenticación:

# Using the MCP tool
# In your AI assistant: "Check auth status"

# Or examine tokens directly
cat tokens.json | jq '.expiresAt'

# Convert timestamp to readable date
date -d @$(($(cat tokens.json | jq -r '.expiresAt') / 1000))

Habilitar registro detallado:

# The server logs to stderr for debugging
mstodo 2> debug.log

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

Haga un fork del repositorio
Cree una rama de características
Ejecute pnpm run lint y pnpm run typecheck antes de enviar
Envíe una solicitud de extracción

Licencia

Licencia MIT - Consulte el archivo LICENSE para más detalles

Reconocimientos

Bifurcación de @jhirono/todomcp
Construido sobre el SDK de Protocolo de Contexto de Modelo
Utiliza la API de Microsoft Graph

Microsoft To Do MCP

Documentación