Servidor MCP Microsoft Office Bridge

MCP Microsoft Office

Um servidor MCP. Vários usuários. Tráfego real do Microsoft 365 no seu tenant de teste.

O Problema

Tenants de teste ficam vazios. Dados de teste estáticos não exercitam fluxos de trabalho reais. Quando você precisa de agentes que enviem e-mails reais, agendem reuniões reais e colaborem em canais reais do Teams, mocks e stubs não são suficientes.

O Que Isto Resolve

Este projeto conecta qualquer cliente de IA compatível com MCP ao Microsoft 365 por meio da Graph API. Cada agente se autentica como um usuário distinto do tenant e realiza operações reais sobre dados reais.

117 ferramentas em 12 módulos: Mail, Calendar, Files, Excel, Word, PowerPoint, Teams, Contacts, To-Do, Groups, People, Search
Multiusuário: um único servidor atende toda a sua equipe, cada um com dados isolados
Chamadas reais à Graph API: cada operação acessa o tenant real, não um mock
Seguro: tokens criptografados em repouso, sem credenciais armazenadas em servidores de terceiros

Arquitetura

                    ┌──────────────────┐
                    │  MCP Client      │
                    │  (Claude, etc.)  │
                    └────────┬─────────┘
                             │ JSON-RPC (stdin/stdout)
                    ┌────────▼─────────┐
                    │  MCP Adapter     │
                    │  (runs locally)  │
                    └────────┬─────────┘
                             │ HTTP + Bearer Token
                    ┌────────▼─────────┐
                    │  MCP Server      │
                    │  (local or       │
                    │   remote)        │
                    └────────┬─────────┘
                             │ Microsoft Graph API
                    ┌────────▼─────────┐
                    │  Microsoft 365   │
                    │  (your tenant)   │
                    └──────────────────┘

Três partes:

Cliente MCP -- a IA com a qual você interage
Adaptador MCP -- um processo Node.js que traduz o protocolo MCP em requisições HTTP (executa na mesma máquina que o cliente)
Servidor MCP -- gerencia a autenticação e chama a API do Microsoft Graph (executa localmente ou em um servidor remoto)

Permissões

O servidor exige 18 permissões delegadas do Microsoft Graph. Doze funcionam sem consentimento de administrador. Seis exigem que um administrador do tenant conceda consentimento.

Sem Consentimento de Administrador

Permissão	Ferramentas Liberadas
`User.Read`	Autenticação, perfil do usuário
`Mail.ReadWrite`	readMail, readMailDetails, markEmailRead, flagMail, getMailAttachments, addMailAttachment, removeMailAttachment
`Mail.Send`	sendMail, replyToMail
`Calendars.ReadWrite`	getEvents, createEvent, updateEvent, cancelEvent, acceptEvent, tentativelyAcceptEvent, declineEvent, getAvailability, findMeetingTimes, getRooms, getCalendars, addAttachment, removeAttachment
`Files.ReadWrite.All`	listFiles, uploadFile, downloadFile, getFileMetadata, getFileContent, setFileContent, updateFileContent, createSharingLink, getSharingLinks, removeSharingPermission, listChannelFiles, uploadFileToChannel, readChannelFile, todas as ferramentas de pastas de trabalho do Excel, todas as ferramentas de Word/PowerPoint
`Contacts.ReadWrite`	listContacts, getContact, createContact, updateContact, deleteContact, searchContacts
`Tasks.ReadWrite`	listTaskLists, getTaskList, createTaskList, updateTaskList, deleteTaskList, listTasks, getTask, createTask, updateTask, deleteTask, completeTask
`Chat.ReadWrite`	listChats, createChat, getChatMessages, sendChatMessage
`Channel.ReadBasic.All`	listTeamChannels, getChannelMessages
`ChannelMessage.Send`	sendChannelMessage, replyToMessage
`Channel.Create`	createTeamChannel
`OnlineMeetings.ReadWrite`	createOnlineMeeting, getOnlineMeeting, listOnlineMeetings, getMeetingByJoinUrl

Exige Consentimento do Administrador

Permissão	Ferramentas Adicionais Liberadas
`User.Read.All`	Resolver IDs de usuários em Teams, pesquisa de People
`People.Read.All`	findPeople, getRelevantPeople, getPersonById
`Group.Read.All`	listGroups, getGroup, listGroupMembers, listMyGroups
`ChannelMember.ReadWrite.All`	addChannelMember
`ChannelMessage.Read.All`	Ler histórico de mensagens do canal
`OnlineMeetingTranscript.Read.All`	getMeetingTranscripts, getMeetingTranscriptContent

Sem consentimento do administrador, você obtém Mail, Calendar, Files, pastas de trabalho do Excel, documentos do Word, apresentações do PowerPoint, Contacts, To-Do, Chat e operações básicas de canais do Teams. Com consentimento do administrador, você adiciona pesquisa de diretório de pessoas, Groups, gerenciamento de membros de canais e transcrições de reuniões.

Início Rápido

Pré-requisitos

Node.js 18+ (download)
Claude Desktop (download) ou outro cliente MCP
Conta Microsoft 365 (corporativa, escolar ou pessoal)

Etapa 1: Registro do Aplicativo no Azure

Acesse Azure Portal > Microsoft Entra ID > App registrations > New registration
Dê o nome de MCP-Microsoft-Office, registre com o tipo de conta de sua preferência
Copie o Application (client) ID e o Directory (tenant) ID
Acesse API permissions > Add a permission > Microsoft Graph > Delegated permissions
Adicione as 18 permissões listadas acima
Se você for administrador do tenant, clique em Grant admin consent
Acesse Authentication > Add a platform > Web
- Redirect URI: http://localhost:3000/api/auth/callback
- Habilite Allow public client flows

Etapa 2: Clonar e Configurar

git clone https://github.com/Aanerud/MCP-Microsoft-Office.git
cd MCP-Microsoft-Office
npm install

Copie .env.example para .env e preencha com os dados do seu aplicativo Azure:

MICROSOFT_CLIENT_ID=your-client-id
MICROSOFT_TENANT_ID=your-tenant-id

Etapa 3: Iniciar o Servidor e Autenticar

npm run dev:web

Abra http://localhost:3000 no seu navegador. Clique em Login with Microsoft, entre e conceda as permissões. Em seguida, clique em Generate MCP Token e copie o token.

Etapa 4: Configurar o Claude Desktop

Edite a configuração do Claude Desktop:

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

O Claude Desktop tem um limite prático de ~55 ferramentas por servidor MCP. Este projeto expõe 117 ferramentas, então as dividimos em três servidores que compartilham o mesmo adaptador e backend:

{
  "mcpServers": {
    "microsoft-365": {
      "command": "node",
      "args": ["/path/to/MCP-Microsoft-Office/mcp-adapter.cjs"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000",
        "MCP_BEARER_TOKEN": "paste-your-token-here",
        "MCP_MODULES": "search,mail,calendar,files,people,contacts,groups,query"
      }
    },
    "microsoft-365-teams": {
      "command": "node",
      "args": ["/path/to/MCP-Microsoft-Office/mcp-adapter.cjs"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000",
        "MCP_BEARER_TOKEN": "paste-your-token-here",
        "MCP_MODULES": "teams,todo"
      }
    },
    "microsoft-365-office": {
      "command": "node",
      "args": ["/path/to/MCP-Microsoft-Office/mcp-adapter.cjs"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000",
        "MCP_BEARER_TOKEN": "paste-your-token-here",
        "MCP_MODULES": "excel,word,powerpoint,files"
      }
    }
  }
}

MCP_MODULES filtra quais módulos o adaptador expõe. Omita-o para expor todas as 117 ferramentas (funciona com clientes que não têm limite de ferramentas).

Defina MCP_DEBUG=1 no bloco env para habilitar o registro de diagnóstico em stderr — útil para solucionar problemas de despacho de ferramentas.

Reinicie o Claude Desktop. Pergunte: "O que tem na minha agenda hoje?" ou "Crie uma pasta de trabalho do Excel com uma tabela de orçamento."

Ferramentas (117)

Mail (9)

Ferramenta	Descrição
`readMail`	Ler mensagens da caixa de entrada
`sendMail`	Enviar um e-mail
`replyToMail`	Responder a um e-mail
`readMailDetails`	Obter o conteúdo completo do e-mail
`markEmailRead`	Marcar e-mail como lido/não lido
`flagMail`	Sinalizar ou remover sinalização de um e-mail
`getMailAttachments`	Listar anexos do e-mail
`addMailAttachment`	Adicionar anexo ao e-mail
`removeMailAttachment`	Remover anexo do e-mail

Calendar (13)

Ferramenta	Descrição
`getEvents`	Obter eventos do calendário
`createEvent`	Criar uma reunião ou evento
`updateEvent`	Modificar um evento existente
`cancelEvent`	Cancelar um evento
`acceptEvent`	Aceitar um convite de reunião
`tentativelyAcceptEvent`	Aceitar provisoriamente
`declineEvent`	Recusar um convite de reunião
`getAvailability`	Verificar horários livres/ocupados
`findMeetingTimes`	Encontrar os melhores horários para reuniões
`getRooms`	Encontrar salas de reunião
`getCalendars`	Listar todos os calendários
`addAttachment`	Adicionar anexo ao evento
`removeAttachment`	Remover anexo do evento

Files (10)

Ferramenta	Descrição
`listFiles`	Listar arquivos do OneDrive
`uploadFile`	Enviar um arquivo
`downloadFile`	Baixar um arquivo
`getFileMetadata`	Obter informações do arquivo
`getFileContent`	Ler o conteúdo do arquivo
`setFileContent`	Gravar o conteúdo do arquivo
`updateFileContent`	Atualizar arquivo existente
`createSharingLink`	Criar um link de compartilhamento
`getSharingLinks`	Listar links de compartilhamento
`removeSharingPermission`	Remover acesso de compartilhamento

Excel (30)

Trabalhe diretamente com pastas de trabalho do Excel armazenadas no OneDrive ou SharePoint — sem necessidade de baixar o arquivo. Todas as operações passam pela API de pastas de trabalho do Microsoft Graph com gerenciamento transparente de sessões.

Ferramenta	Descrição
`createWorkbookSession`	Abrir uma sessão de pasta de trabalho (persistente ou temporária)
`closeWorkbookSession`	Fechar uma sessão ativa de pasta de trabalho
`listWorksheets`	Listar todas as planilhas de uma pasta de trabalho
`addWorksheet`	Adicionar uma nova planilha
`getWorksheet`	Obter uma planilha por nome ou ID
`updateWorksheet`	Renomear, reposicionar ou ocultar uma planilha
`deleteWorksheet`	Excluir uma planilha
`getRange`	Ler valores de célula, fórmulas e formatação
`updateRange`	Gravar valores em um intervalo de células
`getRangeFormat`	Obter formatação (fonte, preenchimento, bordas)
`updateRangeFormat`	Definir formatação (negrito, cores, formatos numéricos)
`sortRange`	Classificar células em um intervalo
`mergeRange`	Mesclar células
`unmergeRange`	Desfazer mesclagem de células
`listTables`	Listar todas as tabelas de uma planilha
`createTable`	Criar uma tabela a partir de um intervalo
`updateTable`	Renomear ou reestilizar uma tabela
`deleteTable`	Excluir uma tabela
`listTableRows`	Listar todas as linhas de uma tabela
`addTableRow`	Adicionar uma linha a uma tabela
`deleteTableRow`	Excluir uma linha por índice
`listTableColumns`	Listar todas as colunas de uma tabela
`addTableColumn`	Adicionar uma coluna a uma tabela
`deleteTableColumn`	Excluir uma coluna
`sortTable`	Classificar uma tabela por coluna
`filterTable`	Aplicar um filtro a uma coluna da tabela
`clearTableFilter`	Limpar um filtro de coluna
`convertTableToRange`	Converter uma tabela de volta em um intervalo comum
`callWorkbookFunction`	Chamar qualquer uma das 300+ funções do Excel (SUM, VLOOKUP, PMT, etc.)
`calculateWorkbook`	Recalcular todas as fórmulas

Word (5)

Crie, leia e converta documentos do Word. Os documentos são criados a partir de JSON estruturado e armazenados no OneDrive. A leitura usa uma cadeia de fallback com múltiplas bibliotecas: mammoth (melhor HTML para .docx) → word-extractor (lida tanto com .doc quanto .docx) → fallback para webUrl. Downloads binários usam o endpoint /contentStream da versão beta do Graph para transferência binária confiável.

Ferramenta	Descrição
`createWordDocument`	Criar um .docx a partir de conteúdo estruturado (títulos, parágrafos, tabelas, listas, imagens)
`readWordDocument`	Ler um documento como HTML e texto simples
`getWordDocumentMetadata`	Obter título, autor, datas, palavras-chave
`getWordDocumentAsHtml`	Converter o conteúdo do documento em HTML
`convertDocumentToPdf`	Converter um documento do Word em PDF

Observação: Alguns tenants do SharePoint convertem arquivos .docx enviados para o formato binário OLE2 em poucos segundos após o upload. Quando isso acontece, as bibliotecas de análise no lado do cliente não conseguem ler o arquivo. O servidor então retorna graciosamente o webUrl para que o usuário possa abrir o documento no navegador.

PowerPoint (4)

Crie, leia e converta apresentações do PowerPoint. As apresentações são construídas a partir de dados estruturados de slides e armazenadas no OneDrive. A leitura usa a conversão HTML do Graph com fallback para jszip para extração de texto em nível de slide.

Ferramenta	Descrição
`createPresentation`	Criar um .pptx com slides de título, conteúdo e em branco
`readPresentation`	Ler o conteúdo dos slides (elementos de texto por slide)
`getPresentationMetadata`	Obter título, autor, número de slides, datas
`convertPresentationToPdf`	Converter uma apresentação em PDF

Teams (21)

Ferramenta	Descrição
`listChats`	Listar chats do Teams
`createChat`	Criar um novo chat
`getChatMessages`	Ler mensagens do chat
`sendChatMessage`	Enviar uma mensagem no chat
`listJoinedTeams`	Listar suas equipes
`listTeamChannels`	Listar canais da equipe
`createTeamChannel`	Criar um canal
`addChannelMember`	Adicionar membro ao canal
`getChannelMessages`	Ler mensagens do canal
`sendChannelMessage`	Publicar em um canal
`replyToMessage`	Responder a uma mensagem do canal
`listChannelFiles`	Listar arquivos em um canal
`uploadFileToChannel`	Enviar arquivo para o canal
`readChannelFile`	Ler um arquivo do canal
`createOnlineMeeting`	Criar uma reunião do Teams
`getOnlineMeeting`	Obter detalhes da reunião
`listOnlineMeetings`	Listar reuniões online
`getMeetingByJoinUrl`	Encontrar reunião pela URL de participação
`getMeetingTranscripts`	Obter transcrições de reuniões
`getMeetingTranscriptContent`	Ler o conteúdo da transcrição

(Observação: addChannelMember se aplica apenas a canais privados. Canais padrão incluem automaticamente todos os membros da equipe.)

Contacts (6)

Ferramenta	Descrição
`listContacts`	Listar contatos
`getContact`	Obter detalhes do contato
`createContact`	Criar um contato
`updateContact`	Atualizar informações do contato
`deleteContact`	Excluir um contato
`searchContacts`	Pesquisar contatos

To-Do (11)

Ferramenta	Descrição
`listTaskLists`	Listar listas de tarefas
`getTaskList`	Obter uma lista de tarefas
`createTaskList`	Criar uma lista de tarefas
`updateTaskList`	Renomear uma lista de tarefas
`deleteTaskList`	Excluir uma lista de tarefas
`listTasks`	Listar tarefas
`getTask`	Obter detalhes da tarefa
`createTask`	Criar uma tarefa
`updateTask`	Atualizar uma tarefa
`deleteTask`	Excluir uma tarefa
`completeTask`	Marcar tarefa como concluída

Grupos (4)

Ferramenta	Descrição
`listGroups`	Listar grupos do Microsoft 365
`getGroup`	Obter detalhes do grupo
`listGroupMembers`	Listar membros do grupo
`listMyGroups`	Listar seus grupos

Pessoas (3)

Ferramenta	Descrição
`findPeople`	Pesquisar no diretório
`getRelevantPeople`	Obter contatos frequentes
`getPersonById`	Obter detalhes da pessoa

Pesquisa (1)

Ferramenta	Descrição
`search`	Pesquisa unificada em e-mails, arquivos, eventos e mensagens de chat

Multiusuário

Cada usuário autentica de forma independente. O servidor isola todos os dados por identidade de usuário.

  Alice (alice@contoso.com)          Bob (bob@contoso.com)
  ├─ Her own Microsoft tokens        ├─ His own Microsoft tokens
  ├─ Her own session                  ├─ His own session
  └─ Claude Desktop (her laptop)     └─ Claude Desktop (his PC)

              Complete data isolation.
         Alice never sees Bob's data.

Para testes automatizados com múltiplos agentes, use o fluxo ROPC (Resource Owner Password Credentials) para autenticar programaticamente:

# Start the server
npm run dev:web

# Run the E2E test suite (authenticates 3 users via ROPC)
node tests/run-all.cjs

A suíte de testes autentica vários usuários e, em seguida, exercita todas as 117 ferramentas em 12 módulos, além de 5 fluxos de trabalho entre módulos. Consulte tests/ para a implementação completa.

Suíte de Testes E2E

O projeto inclui uma suíte de testes abrangente que cobre todas as 117 ferramentas.

# Run all tests (requires server running)
node tests/run-all.cjs

# Run a single module
node tests/run-all.cjs --bucket mail --buckets-only

# Run only workflows
node tests/run-all.cjs --workflows-only

Estrutura de testes:

tests/
  lib/           Shared auth, HTTP client, reporter
  buckets/       One file per module (12 files, 117 tools)
  workflows/     Cross-module tests (5 files)
  run-all.cjs    Master runner

Os testes autenticam via ROPC (sem gerenciamento manual de tokens) e são executados em ~100 segundos.

Variáveis de Ambiente

Copie .env.example para .env e configure:

Variável	Obrigatória	Descrição
`MICROSOFT_CLIENT_ID`	Sim	ID do Cliente do Azure App
`MICROSOFT_TENANT_ID`	Sim	ID do Locatário do Azure
`MICROSOFT_REDIRECT_URI`	Não	URL de retorno de chamada OAuth (padrão: `http://localhost:3000/api/auth/callback`)
`DEVICE_REGISTRY_ENCRYPTION_KEY`	Produção	Chave de criptografia de 32 bytes para armazenamento de tokens
`JWT_SECRET`	Produção	Segredo para assinar tokens JWT
`CORS_ALLOWED_ORIGINS`	Produção	Origens permitidas separadas por vírgula
`PORT`	Não	Porta do servidor (padrão: `3000`)
`NODE_ENV`	Não	`development` ou `production`

Implantação

Local (Recomendado para Começar)

npm install
npm run dev:web

Azure App Service

Consulte docs/azure-deployment.md para implantação CI/CD com GitHub Actions.

Segurança

Armazenamento criptografado: todos os tokens da Microsoft são criptografados em repouso com AES-256
Sem segredos de cliente: usa fluxo de cliente público (PKCE) para autenticação em desktop
Isolamento de tokens: os tokens de cada usuário são armazenados separadamente com chaves de criptografia diferentes
Limitação de taxa: limitação de taxa integrada protege contra abuso
Proteção CORS: lista de permissões de origem em produção
Expiração de sessão: as sessões expiram após 24 horas

Checklist de Produção

Definir NODE_ENV=production
Definir DEVICE_REGISTRY_ENCRYPTION_KEY (32 bytes)
Definir JWT_SECRET (string aleatória forte)
Definir CORS_ALLOWED_ORIGINS
Usar HTTPS com um certificado válido

Estrutura do Projeto

MCP-Microsoft-Office/
├── mcp-adapter.cjs          MCP protocol adapter (runs locally with Claude Desktop)
├── src/
│   ├── api/                 Express routes and controllers
│   ├── auth/                MSAL authentication (OAuth2, ROPC, token exchange)
│   ├── core/                Services (cache, storage, tools, error handling)
│   ├── graph/               Microsoft Graph API services
│   │   ├── graph-client.cjs   HTTP client with retry, binary support, sessions
│   │   ├── files-service.cjs  OneDrive file operations
│   │   ├── excel-service.cjs  Workbook API (sessions, ranges, tables, functions)
│   │   ├── word-service.cjs   Word create/read (docx + mammoth + word-extractor)
│   │   └── powerpoint-service.cjs  PPT create/read (pptxgenjs + jszip)
│   └── modules/             Feature modules (mail, calendar, excel, word, powerpoint, etc.)
├── public/                  Web UI for authentication
└── tests/                   E2E test suite (gitignored)

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Envie um pull request

Licença

Licença MIT — consulte o arquivo LICENSE.

MCP Microsoft Office Bridge

Documentação