Servidor MCP de Microsoft Office Bridge

MCP Microsoft Office

Un servidor MCP. Múltiples usuarios. Tráfico real de Microsoft 365 en tu inquilino de prueba.

El problema

Los inquilinos de prueba permanecen vacíos. Los datos de prueba estáticos no ejercitan flujos de trabajo reales. Cuando necesitas agentes que envíen correos reales, programen reuniones reales y colaboren en canales reales de Teams, los mocks y stubs se quedan cortos.

Qué resuelve esto

Este proyecto conecta cualquier cliente de IA compatible con MCP a Microsoft 365 a través de la Graph API. Cada agente se autentica como un usuario distinto del inquilino y realiza operaciones reales sobre datos reales.

117 herramientas en 12 módulos: Mail, Calendar, Files, Excel, Word, PowerPoint, Teams, Contacts, To-Do, Groups, People, Search
Multiusuario: un solo servidor admite a todo tu equipo, cada uno con datos aislados
Llamadas reales a la Graph API: cada operación llega al inquilino real, no a un mock
Seguro: tokens cifrados en reposo, sin credenciales almacenadas en servidores de terceros

Arquitectura

                    ┌──────────────────┐
                    │  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)   │
                    └──────────────────┘

Tres partes:

Cliente MCP -- la IA con la que interactúas
Adaptador MCP -- un proceso de Node.js que traduce el protocolo MCP a solicitudes HTTP (se ejecuta en la misma máquina que el cliente)
Servidor MCP -- gestiona la autenticación y llama a la Microsoft Graph API (se ejecuta localmente o en un servidor remoto)

Permisos

El servidor requiere 18 permisos delegados de Microsoft Graph. Doce funcionan sin consentimiento de administrador. Seis requieren que un administrador del inquilino otorgue su consentimiento.

Sin consentimiento de administrador requerido

Permiso	Herramientas desbloqueadas
`User.Read`	Autenticación, perfil de usuario
`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 las herramientas de libros de Excel, todas las herramientas 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

Requiere consentimiento de administrador

Permiso	Herramientas adicionales desbloqueadas
`User.Read.All`	Resolver IDs de usuario en Teams, búsqueda de People
`People.Read.All`	findPeople, getRelevantPeople, getPersonById
`Group.Read.All`	listGroups, getGroup, listGroupMembers, listMyGroups
`ChannelMember.ReadWrite.All`	addChannelMember
`ChannelMessage.Read.All`	Leer historial de mensajes del canal
`OnlineMeetingTranscript.Read.All`	getMeetingTranscripts, getMeetingTranscriptContent

Sin consentimiento de administrador, obtienes Mail, Calendar, Files, libros de Excel, documentos de Word, presentaciones de PowerPoint, Contacts, To-Do, Chat y operaciones básicas de canales de Teams. Con consentimiento de administrador, añades búsqueda en el directorio de People, Groups, gestión de miembros de canales y transcripciones de reuniones.

Inicio rápido

Requisitos previos

Node.js 18+ (descargar)
Claude Desktop (descargar) u otro cliente MCP
Cuenta de Microsoft 365 (de trabajo, educativa o personal)

Paso 1: Registro de aplicación en Azure

Ve a Azure Portal > Microsoft Entra ID > Registros de aplicaciones > Nuevo registro
Nómbralo MCP-Microsoft-Office, regístralo con tu tipo de cuenta preferido
Copia el ID de aplicación (cliente) y el ID de directorio (inquilino)
Ve a Permisos de API > Agregar un permiso > Microsoft Graph > Permisos delegados
Añade los 18 permisos enumerados anteriormente
Si eres administrador del inquilino, haz clic en Otorgar consentimiento de administrador
Ve a Autenticación > Agregar una plataforma > Web
- URI de redirección: http://localhost:3000/api/auth/callback
- Habilita Permitir flujos de clientes públicos

Paso 2: Clonar y configurar

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

Copia .env.example a .env y completa los detalles de tu aplicación de Azure:

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

Paso 3: Iniciar el servidor y autenticarse

npm run dev:web

Abre http://localhost:3000 en tu navegador. Haz clic en Iniciar sesión con Microsoft, inicia sesión y otorga permisos. Luego haz clic en Generar token MCP y copia el token.

Paso 4: Configurar Claude Desktop

Edita tu configuración de Claude Desktop:

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

Claude Desktop tiene un límite práctico de ~55 herramientas por servidor MCP. Este proyecto expone 117 herramientas, por lo que las dividimos en tres servidores que comparten el mismo adaptador y 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 qué módulos expone el adaptador. Omítelo para exponer las 117 herramientas (funciona con clientes que no tienen límite de herramientas).

Establece MCP_DEBUG=1 en el bloque env para habilitar el registro de diagnóstico en stderr — útil para solucionar problemas de despacho de herramientas.

Reinicia Claude Desktop. Pregunta: "¿Qué hay en mi calendario hoy?" o "Crea un libro de Excel con una tabla de presupuesto."

Herramientas (117)

Mail (9)

Herramienta	Descripción
`readMail`	Leer mensajes de la bandeja de entrada
`sendMail`	Enviar un correo electrónico
`replyToMail`	Responder a un correo electrónico
`readMailDetails`	Obtener el contenido completo del correo
`markEmailRead`	Marcar correo como leído/no leído
`flagMail`	Marcar o desmarcar un correo
`getMailAttachments`	Listar archivos adjuntos del correo
`addMailAttachment`	Añadir archivo adjunto al correo
`removeMailAttachment`	Eliminar archivo adjunto del correo

Calendar (13)

Herramienta	Descripción
`getEvents`	Obtener eventos del calendario
`createEvent`	Crear una reunión o evento
`updateEvent`	Modificar un evento existente
`cancelEvent`	Cancelar un evento
`acceptEvent`	Aceptar una invitación a reunión
`tentativelyAcceptEvent`	Aceptar provisionalmente
`declineEvent`	Rechazar una invitación a reunión
`getAvailability`	Consultar disponibilidad (libre/ocupado)
`findMeetingTimes`	Encontrar horarios óptimos de reunión
`getRooms`	Encontrar salas de reuniones
`getCalendars`	Listar todos los calendarios
`addAttachment`	Añadir archivo adjunto al evento
`removeAttachment`	Eliminar archivo adjunto del evento

Files (10)

Herramienta	Descripción
`listFiles`	Listar archivos de OneDrive
`uploadFile`	Subir un archivo
`downloadFile`	Descargar un archivo
`getFileMetadata`	Obtener información del archivo
`getFileContent`	Leer contenido del archivo
`setFileContent`	Escribir contenido del archivo
`updateFileContent`	Actualizar archivo existente
`createSharingLink`	Crear un enlace de uso compartido
`getSharingLinks`	Listar enlaces de uso compartido
`removeSharingPermission`	Eliminar acceso de uso compartido

Excel (30)

Trabaja directamente con libros de Excel almacenados en OneDrive o SharePoint — sin necesidad de descargar archivos. Todas las operaciones pasan por la API de libros de Microsoft Graph con gestión transparente de sesiones.

Herramienta	Descripción
`createWorkbookSession`	Abrir una sesión de libro (persistente o temporal)
`closeWorkbookSession`	Cerrar una sesión de libro activa
`listWorksheets`	Listar todas las hojas de cálculo de un libro
`addWorksheet`	Añadir una nueva hoja de cálculo
`getWorksheet`	Obtener una hoja de cálculo por nombre o ID
`updateWorksheet`	Renombrar, reposicionar u ocultar una hoja de cálculo
`deleteWorksheet`	Eliminar una hoja de cálculo
`getRange`	Leer valores de celda, fórmulas y formato
`updateRange`	Escribir valores en un rango de celdas
`getRangeFormat`	Obtener formato (fuente, relleno, bordes)
`updateRangeFormat`	Establecer formato (negrita, colores, formatos numéricos)
`sortRange`	Ordenar celdas en un rango
`mergeRange`	Combinar celdas
`unmergeRange`	Separar celdas
`listTables`	Listar todas las tablas de una hoja de cálculo
`createTable`	Crear una tabla a partir de un rango
`updateTable`	Renombrar o cambiar el estilo de una tabla
`deleteTable`	Eliminar una tabla
`listTableRows`	Listar todas las filas de una tabla
`addTableRow`	Añadir una fila a una tabla
`deleteTableRow`	Eliminar una fila por índice
`listTableColumns`	Listar todas las columnas de una tabla
`addTableColumn`	Añadir una columna a una tabla
`deleteTableColumn`	Eliminar una columna
`sortTable`	Ordenar una tabla por columna
`filterTable`	Aplicar un filtro a una columna de tabla
`clearTableFilter`	Limpiar un filtro de columna
`convertTableToRange`	Convertir una tabla de nuevo a un rango simple
`callWorkbookFunction`	Llamar a cualquiera de las más de 300 funciones de Excel (SUM, VLOOKUP, PMT, etc.)
`calculateWorkbook`	Recalcular todas las fórmulas

Word (5)

Crea, lee y convierte documentos de Word. Los documentos se crean a partir de JSON estructurado y se almacenan en OneDrive. La lectura utiliza una cadena de respaldo de múltiples bibliotecas: mammoth (mejor HTML para .docx) → word-extractor (maneja tanto .doc como .docx) → respaldo webUrl. Las descargas binarias utilizan el endpoint /contentStream de la versión beta de Graph para una transferencia binaria fiable.

Herramienta	Descripción
`createWordDocument`	Crear un .docx a partir de contenido estructurado (encabezados, párrafos, tablas, listas, imágenes)
`readWordDocument`	Leer un documento como HTML y texto plano
`getWordDocumentMetadata`	Obtener título, autor, fechas, palabras clave
`getWordDocumentAsHtml`	Convertir el contenido del documento a HTML
`convertDocumentToPdf`	Convertir un documento de Word a PDF

Nota: Algunos inquilinos de SharePoint convierten los archivos .docx subidos a formato binario OLE2 en cuestión de segundos tras la carga. Cuando esto ocurre, las bibliotecas de análisis del lado del cliente no pueden leer el archivo. El servidor recurre elegantemente a devolver el webUrl para que el usuario pueda abrir el documento en el navegador.

PowerPoint (4)

Crea, lee y convierte presentaciones de PowerPoint. Las presentaciones se construyen a partir de datos estructurados de diapositivas y se almacenan en OneDrive. La lectura utiliza la conversión HTML de Graph con respaldo de jszip para la extracción de texto a nivel de diapositiva.

Herramienta	Descripción
`createPresentation`	Crear un .pptx con diapositivas de título, contenido y en blanco
`readPresentation`	Leer contenido de diapositivas (elementos de texto por diapositiva)
`getPresentationMetadata`	Obtener título, autor, número de diapositivas, fechas
`convertPresentationToPdf`	Convertir una presentación a PDF

Teams (21)

Herramienta	Descripción
`listChats`	Listar chats de Teams
`createChat`	Crear un nuevo chat
`getChatMessages`	Leer mensajes de chat
`sendChatMessage`	Enviar un mensaje de chat
`listJoinedTeams`	Listar tus equipos
`listTeamChannels`	Listar canales de equipo
`createTeamChannel`	Crear un canal
`addChannelMember`	Añadir miembro al canal
`getChannelMessages`	Leer mensajes del canal
`sendChannelMessage`	Publicar en un canal
`replyToMessage`	Responder a un mensaje del canal
`listChannelFiles`	Listar archivos en un canal
`uploadFileToChannel`	Subir archivo al canal
`readChannelFile`	Leer un archivo del canal
`createOnlineMeeting`	Crear una reunión de Teams
`getOnlineMeeting`	Obtener detalles de la reunión
`listOnlineMeetings`	Listar reuniones en línea
`getMeetingByJoinUrl`	Encontrar reunión por URL de unión
`getMeetingTranscripts`	Obtener transcripciones de reuniones
`getMeetingTranscriptContent`	Leer contenido de la transcripción

(Nota: addChannelMember se aplica solo a canales privados. Los canales estándar incluyen automáticamente a todos los miembros del equipo.)

Contacts (6)

Herramienta	Descripción
`listContacts`	Listar contactos
`getContact`	Obtener detalles del contacto
`createContact`	Crear un contacto
`updateContact`	Actualizar información del contacto
`deleteContact`	Eliminar un contacto
`searchContacts`	Buscar contactos

To-Do (11)

Herramienta	Descripción
`listTaskLists`	Listar listas de tareas
`getTaskList`	Obtener una lista de tareas
`createTaskList`	Crear una lista de tareas
`updateTaskList`	Renombrar una lista de tareas
`deleteTaskList`	Eliminar una lista de tareas
`listTasks`	Listar tareas
`getTask`	Obtener detalles de una tarea
`createTask`	Crear una tarea
`updateTask`	Actualizar una tarea
`deleteTask`	Eliminar una tarea
`completeTask`	Marcar tarea como completada

Grupos (4)

Herramienta	Descripción
`listGroups`	Listar grupos de Microsoft 365
`getGroup`	Obtener detalles de un grupo
`listGroupMembers`	Listar miembros de un grupo
`listMyGroups`	Listar tus grupos

Personas (3)

Herramienta	Descripción
`findPeople`	Buscar en el directorio
`getRelevantPeople`	Obtener contactos frecuentes
`getPersonById`	Obtener detalles de una persona

Búsqueda (1)

Herramienta	Descripción
`search`	Búsqueda unificada en correos, archivos, eventos y mensajes de chat

Multi-Usuario

Cada usuario se autentica de forma independiente. El servidor aísla todos los datos por identidad de usuario.

  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 pruebas automatizadas con múltiples agentes, use el flujo ROPC (Resource Owner Password Credentials) para autenticarse programáticamente:

# Start the server
npm run dev:web

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

El conjunto de pruebas autentica a múltiples usuarios y luego ejercita las 117 herramientas en 12 módulos más 5 flujos de trabajo entre módulos. Consulte tests/ para la implementación completa.

Conjunto de Pruebas E2E

El proyecto incluye un conjunto de pruebas integral que cubre las 117 herramientas.

# 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

Estructura de pruebas:

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

Las pruebas se autentican mediante ROPC (sin gestión manual de tokens) y se ejecutan en ~100 segundos.

Variables de Entorno

Copie .env.example a .env y configure:

Variable	Requerida	Descripción
`MICROSOFT_CLIENT_ID`	Sí	ID de cliente de la aplicación Azure
`MICROSOFT_TENANT_ID`	Sí	ID de inquilino de Azure
`MICROSOFT_REDIRECT_URI`	No	URL de devolución de llamada OAuth (predeterminado: `http://localhost:3000/api/auth/callback`)
`DEVICE_REGISTRY_ENCRYPTION_KEY`	Producción	Clave de cifrado de 32 bytes para el almacenamiento de tokens
`JWT_SECRET`	Producción	Secreto para firmar tokens JWT
`CORS_ALLOWED_ORIGINS`	Producción	Orígenes permitidos separados por comas
`PORT`	No	Puerto del servidor (predeterminado: `3000`)
`NODE_ENV`	No	`development` o `production`

Despliegue

Local (Recomendado para Empezar)

npm install
npm run dev:web

Azure App Service

Consulte docs/azure-deployment.md para el despliegue CI/CD con GitHub Actions.

Seguridad

Almacenamiento cifrado: todos los tokens de Microsoft se cifran en reposo con AES-256
Sin secretos de cliente: usa flujo de cliente público (PKCE) para autenticación de escritorio
Aislamiento de tokens: los tokens de cada usuario se almacenan por separado con diferentes claves de cifrado
Limitación de velocidad: la limitación de velocidad integrada protege contra el abuso
Protección CORS: lista blanca de orígenes en producción
Caducidad de sesión: las sesiones caducan después de 24 horas

Lista de Verificación de Producción

Establecer NODE_ENV=production
Establecer DEVICE_REGISTRY_ENCRYPTION_KEY (32 bytes)
Establecer JWT_SECRET (cadena aleatoria fuerte)
Establecer CORS_ALLOWED_ORIGINS
Usar HTTPS con un certificado válido

Estructura del Proyecto

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)

Contribuciones

Haga un fork del repositorio
Cree una rama de características
Realice sus cambios
Envíe una solicitud de extracción

Licencia

Licencia MIT -- consulte el archivo LICENSE.

MCP Microsoft Office Bridge

Documentación