todo-mcp

Conecte o Claude ao seu Microsoft To Do. Servidor MCP remoto, pronto para a Vercel, que permite ao Claude ler, criar e concluir tarefas do Microsoft To Do de uma conta pessoal (outlook.com, hotmail.com, live.com) através da Microsoft Graph API.

🇺🇸 English summary: a self-hosted remote MCP server (Vercel + Supabase) that gives Claude read/write access to your own Microsoft To Do via Microsoft Graph. Each person deploys their own copy with their own Microsoft app registration — no data is shared with anyone else. Tool names and messages are in Portuguese. See Quick start.

Por que existe

O Microsoft To Do já sincroniza entre celular, computador e web, mas não há um conector oficial para o Claude. Este projeto preenche essa lacuna sem trocar de app de tarefas: você continua usando o To Do normalmente e o Claude passa a enxergar e organizar as mesmas listas.

Exemplos do que dá para pedir ao Claude:

• "Quais são minhas tarefas de hoje e o que está atrasado?"

• "Crie uma tarefa 'Renovar seguro' na lista Pessoal para sexta, com lembrete às 9h."

• "Marque como feita a etapa 'Revisar contrato' da tarefa X."

• "Monte meu plano do dia a partir das tarefas vencendo hoje."

Related MCP server: mstodo

Como funciona

Claude ──(MCP / HTTPS)──▶ Vercel: /api/mcp/<segredo>
                              │
                              ├─▶ Supabase: lê o refresh token da sua conta
                              ├─▶ Microsoft identity: troca por um access token
                              └─▶ Microsoft Graph: /me/todo/lists/...

• Uma instância = uma pessoa. Cada usuário faz o próprio deploy, com o próprio app no Microsoft Entra e o próprio banco. Nada passa por servidores de terceiros além de Vercel, Supabase e Microsoft.

• Permissões delegadas. Contas pessoais da Microsoft não aceitam permissões de aplicativo; o servidor age em seu nome usando o refresh token obtido no login único.

• Stateless. Cada chamada MCP cria um servidor novo, o que combina com funções serverless.

Ferramentas

Concluir uma tarefa recorrente pelo Graph gera a próxima ocorrência, como no app. Datas usam o formato AAAA-MM-DD e o fuso configurado em LOCAL_TZ / GRAPH_TIMEZONE.

Requisitos

• Node.js 20+

• Conta na Vercel (plano gratuito serve)

• Projeto no Supabase (plano gratuito serve)

• Conta pessoal da Microsoft com o To Do

• Acesso ao portal do Azure para registrar o app (gratuito)

Passo a passo

1. Clonar e verificar

git clone https://github.com/<seu-usuario>/todo-mcp.git
cd todo-mcp
npm install
npm run typecheck
npm run test:tools   # lista as ferramentas sem acessar a rede

2. Criar a tabela no Supabase

Rode sql/001_ms_todo_tokens.sql no SQL Editor. A tabela tem RLS ligado e nenhuma policy: só a service role (usada pelo backend) acessa. Recomenda-se um projeto dedicado em vez de reaproveitar o banco de outra aplicação.

3. Registrar o app no Microsoft Entra

1. Microsoft Entra ID → Registros de aplicativo → Novo registro. Se o portal pedir um diretório, crie uma conta Azure gratuita com sua conta Microsoft.

2. Tipos de conta: Somente contas pessoais da Microsoft (corresponde a MS_TENANT=consumers).

3. URI de redirecionamento: plataforma Web, https://<seu-dominio>/api/auth/callback.

4. Certificados e segredos → Novo segredo do cliente. Copie o Valor (aparece uma única vez).

5. Permissões de API → Microsoft Graph → Delegadas: Tasks.ReadWrite, User.Read, offline_access.

4. Configurar e publicar na Vercel

Copie .env.example e preencha as variáveis na Vercel (Settings → Environment Variables):

Gere o MCP_SECRET:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Depois: vercel deploy --prod (ou conecte o repositório na Vercel).

5. Autorizar sua conta Microsoft (uma vez)

Abra no navegador https://<seu-dominio>/api/auth/login?key=<MCP_SECRET>, entre com sua conta e aceite as permissões. A página deve mostrar Conectado ✓.

6. Adicionar ao Claude

Em Conectores, adicione um conector personalizado com a URL:

https://<seu-dominio>/api/mcp/<MCP_SECRET>

Teste com: "quais são minhas tarefas de hoje no To Do?"

Segurança

• Nunca faça commit de .env. Ele já está no .gitignore; use as variáveis de ambiente da Vercel.

• A URL do conector contém o segredo e funciona como uma senha. Se vazar, troque o MCP_SECRET e atualize o conector. Requisições com segredo errado recebem 404.

• O login OAuth também exige o segredo, impedindo que outra pessoa conecte a conta dela na sua instância. O parâmetro state é validado via cookie.

• Escopo mínimo: apenas tarefas (Tasks.ReadWrite) e o perfil básico (User.Read). Sem acesso a e-mail, arquivos ou calendário.

• Revogar acesso: em account.live.com/consent/Manage remova o app, ou apague a linha em ms_todo_tokens.

• O refresh token expira após longos períodos sem uso; as ferramentas avisam, e basta refazer o passo 5.

Encontrou uma falha? Abra uma issue sem incluir tokens, segredos ou dados pessoais.

Limitações conhecidas

• Uma conta Microsoft por instância.

• Autenticação do conector por segredo na URL; OAuth no próprio conector está no roteiro.

• Recorrência de tarefas é exibida, mas ainda não pode ser criada ou editada pelas ferramentas.

• Listas compartilhadas aparecem normalmente, mas não houve testes extensivos com elas.

Roteiro

• OAuth no endpoint MCP (dispensa o segredo na URL)

• Criar e editar recorrência

• Mover tarefas entre listas

• Busca por texto em todas as listas

• Notificações de mudança via webhooks do Graph

Estrutura

api/mcp/[key].ts       endpoint MCP (Streamable HTTP, stateless)
api/auth/login.ts      inicia o OAuth da Microsoft
api/auth/callback.ts   recebe o código e salva o refresh token
lib/env.ts             variáveis de ambiente e comparação segura do segredo
lib/msauth.ts          troca, renovação e cache de tokens
lib/tokens.ts          leitura/gravação do refresh token no Supabase
lib/graph.ts           cliente HTTP do Microsoft Graph (paginação, erros)
lib/todo.ts            regras do To Do: listas, tarefas, datas, formatação
lib/server.ts          definição das ferramentas MCP
scripts/list-tools.ts  teste local sem rede
sql/                   migrations do Supabase

Contribuindo

Contribuições são bem-vindas. Antes de abrir um PR, rode npm run typecheck e npm run test:tools. O CI roda os mesmos comandos.

Licença

MIT. Projeto independente, sem afiliação com Microsoft ou Anthropic. "Microsoft To Do" é marca da Microsoft.