Microsoft To Do MCP

Interaja com o Microsoft To Do usando a API do Microsoft Graph.

Documentação

Microsoft To Do MCP

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA como Claude e Cursor interajam com o Microsoft To Do por meio da API Microsoft Graph. Este serviço oferece recursos abrangentes de gerenciamento de tarefas por meio de um fluxo de autenticação OAuth 2.0 seguro.

Recursos

15 Ferramentas MCP: Funcionalidade completa de gerenciamento de tarefas, incluindo listas, tarefas, itens de checklist e recursos de organização
Autenticação Perfeita: Renovação automática de token sem intervenção manual
Autenticação OAuth 2.0: Autenticação segura com renovação automática de token
Integração com a API Microsoft Graph: Integração direta com a API oficial da Microsoft
Suporte Multi-inquilino: Funciona com contas pessoais, corporativas e escolares da Microsoft
TypeScript: Totalmente tipado para confiabilidade e experiência do desenvolvedor
Módulos ESM: Sistema moderno de módulos JavaScript

Pré-requisitos

Node.js 16 ou superior (testado com Node.js 18.x, 20.x e 22.x)
Gerenciador de pacotes pnpm
Uma conta Microsoft (pessoal, corporativa ou escolar)
Registro de aplicativo no Azure (veja a configuração abaixo)

Instalação

Opção 1: Instalação 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

O pacote fornece três aliases de comando:

microsoft-todo-mcp-server - Nome completo do pacote
mstodo - Alias curto para o servidor MCP
mstodo-config - Ferramenta auxiliar de configuração

Opção 2: Clonar e Executar Localmente

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

Registro de Aplicativo no Azure

Acesse o Portal do Azure
Navegue até "Registros de aplicativo" e crie um novo registro
Dê um nome ao seu aplicativo (por exemplo, "To Do MCP")
Para "Tipos de conta suportados", selecione uma das seguintes opções conforme sua necessidade:
- Somente contas neste diretório organizacional (Inquilino único) - Para uso dentro de uma única organização
- Contas em qualquer diretório organizacional (Qualquer diretório do Azure AD - Multinquilino) - Para uso em várias organizações
- Contas em qualquer diretório organizacional e contas pessoais da Microsoft - Para contas corporativas e pessoais
Defina o URI de redirecionamento para http://localhost:3000/callback
Após criar o aplicativo, vá para "Certificados e segredos" e crie um novo segredo de cliente
Vá para "Permissões de API" e adicione as seguintes permissões:
- Microsoft Graph > Permissões delegadas:
  - Tasks.Read
  - Tasks.ReadWrite
  - User.Read
Clique em "Conceder consentimento do administrador" para essas permissões

Configuração

Configuração do Ambiente

Crie um arquivo .env na raiz do projeto (necessário para autenticação):

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

Opções de TENANT_ID

organizations - Para contas organizacionais multinquilino (padrão se não especificado)
consumers - Somente para contas pessoais da Microsoft
common - Para contas organizacionais e pessoais
your-specific-tenant-id - Para configurações de inquilino único

Exemplos:

# 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

Armazenamento de Token

O servidor armazena tokens de autenticação em tokens.json com renovação automática 5 minutos antes da expiração. Você pode substituir o local do arquivo de token:

# 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

Fluxo de Trabalho de Configuração Completo

Etapa 1: Autenticar com a 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

Isso abre uma janela do navegador para autenticação da Microsoft e cria um arquivo tokens.json.

Etapa 2: Criar Configuração MCP

# Generate MCP configuration file
pnpm run create-config

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

Isso cria um arquivo mcp.json com seus tokens de autenticação.

Etapa 3: Configurar Seu Assistente de IA

Para Claude Desktop:

Adicione ao seu arquivo de configuração:

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 Disponíveis

# 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

Ferramentas MCP

O servidor fornece 13 ferramentas para gerenciamento abrangente do Microsoft To Do:

Autenticação

auth-status - Verificar status de autenticação, expiração de token e tipo de conta

Listas de Tarefas (Contêineres de Nível Superior)

get-task-lists - Recuperar todas as listas de tarefas com metadados (padrão, compartilhadas, etc.)
create-task-list - Criar uma nova lista de tarefas
update-task-list - Renomear uma lista de tarefas existente
delete-task-list - Excluir uma lista de tarefas e todo o seu conteúdo

Tarefas (Itens de Tarefas Principais)

get-tasks - Obter tarefas de uma lista com filtragem, classificação e paginação
- Suporta parâmetros de consulta OData: $filter, $select, $orderby, $top, $skip, $count
create-task - Criar uma nova tarefa com suporte completo a propriedades
- Título, descrição, data de vencimento, data de início, importância, lembretes, status, categorias
update-task - Atualizar qualquer propriedade de tarefa
delete-task - Excluir uma tarefa e todos os seus itens de checklist

Itens de Checklist (Subtarefas)

get-checklist-items - Obter subtarefas de uma tarefa específica
create-checklist-item - Adicionar uma nova subtarefa a uma tarefa
update-checklist-item - Atualizar texto da subtarefa ou status de conclusão
delete-checklist-item - Remover uma subtarefa específica

Arquitetura

Estrutura do Projeto

Servidor MCP (src/todo-index.ts) - Servidor principal que implementa o protocolo MCP
Wrapper CLI (src/cli.ts) - Ponto de entrada executável com gerenciamento de token
Servidor de Autenticação (src/auth-server.ts) - Servidor Express para fluxo OAuth 2.0
Gerador de Configuração (src/create-mcp-config.ts) - Auxiliar para criar configurações MCP

Detalhes Técnicos

API Microsoft Graph: Usa endpoints v1.0
Autenticação: MSAL (Microsoft Authentication Library) com fluxo PKCE
Gerenciamento de Token: Renovação automática 5 minutos antes da expiração
Sistema de Build: ts-builds (tsdown) para compilação rápida de TypeScript
Sistema de Módulos: ESM (módulos ECMAScript)

Limitações e Problemas Conhecidos

Contas Pessoais da Microsoft

Erro MailboxNotEnabledForRESTAPI: Contas pessoais da Microsoft (outlook.com, hotmail.com, live.com) têm acesso limitado à API do To Do por meio do Microsoft Graph
Esta é uma limitação do serviço da Microsoft, não um problema deste aplicativo
Contas corporativas/escolares têm acesso completo à API

Limitações da API

Limites de taxa se aplicam de acordo com as políticas da Microsoft
Alguns recursos podem não estar disponíveis para contas pessoais
Listas compartilhadas têm funcionalidade limitada

Solução de Problemas

Problemas de Autenticação

Falhas na aquisição de token

Verifique CLIENT_ID, CLIENT_SECRET e TENANT_ID no seu arquivo .env
Certifique-se de que o URI de redirecionamento corresponda exatamente: http://localhost:3000/callback
Verifique se as permissões do Azure App foram concedidas com consentimento do administrador

Problemas de permissão

Certifique-se de que todas as permissões necessárias da Graph API foram adicionadas e consentidas
Para contas organizacionais, o consentimento do administrador pode ser necessário

Configuração do Tipo de Conta

Contas Corporativas/Escolares

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

Contas Pessoais

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

Depuração

Verificar status de autenticação:

# 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 detalhado:

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

Contribuição

Contribuições são bem-vindas! Por favor:

Faça um fork do repositório
Crie um branch de recurso
Execute pnpm run lint e pnpm run typecheck antes de enviar
Envie um pull request

Licença

Licença MIT - Consulte o arquivo LICENSE para detalhes

Agradecimentos

Fork de @jhirono/todomcp
Construído sobre o Model Context Protocol SDK
Usa a API Microsoft Graph

Microsoft To Do MCP

Documentação