Teams MCP

Interactúa con Microsoft Teams, usuarios y datos organizacionales a través de la API de Microsoft Graph.

GitHub
130
Prueba este MCPPatrocinado

Documentación

Teams MCP

npm version npm downloads codecov License: MIT GitHub stars

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona una integración perfecta con las API de Microsoft Graph, permitiendo que los asistentes de IA interactúen con Microsoft Teams, usuarios, chats, archivos y datos organizativos.

Teams MCP server

📦 Instalación

Para usar este servidor MCP en Cursor/Claude/VS Code, añade la siguiente configuración:

{
  "mcpServers": {
    "teams-mcp": {
      "command": "npx",
      "args": ["-y", "@floriscornel/teams-mcp@latest"]
    }
  }
}

🚀 Características

🔐 Autenticación

  • Flujo de autenticación con código de dispositivo OAuth 2.0 con Microsoft Graph
  • Gestión segura de tokens, persistencia de caché y renovación de tokens de actualización
  • Verificación del estado de autenticación y soporte de cierre de sesión
  • Modo de solo lectura con ámbitos reducidos
  • Soporte directo de AUTH_TOKEN para tokens de acceso de Microsoft Graph emitidos previamente

👥 Gestión de Usuarios

  • Obtener información del usuario actual
  • Buscar usuarios por nombre o correo electrónico
  • Recuperar perfiles de usuario detallados
  • Acceder a los datos del directorio organizativo

🏢 Integración con Microsoft Teams

  • Gestión de Equipos

    • Listar los equipos a los que se ha unido el usuario
    • Acceder a los detalles y metadatos del equipo

  • Operaciones de Canales

    • Listar canales dentro de los equipos
    • Recuperar mensajes y respuestas de canales
    • Enviar mensajes a canales de equipo
    • Responder a hilos de canales existentes
    • Editar y eliminar suavemente mensajes y respuestas de canales
    • Soporte para niveles de importancia de mensajes (normal, high, urgent)
    • Soporte para adjuntos de imágenes en línea mediante URL o datos base64

  • Miembros del Equipo

    • Listar miembros del equipo y sus roles
    • Acceder a la información de los miembros
    • Buscar usuarios para @mentions

💬 Chat y Mensajería

  • Chats 1:1 y Grupales
    • Listar los chats del usuario
    • Crear nuevas conversaciones 1:1 o grupales
    • Recuperar el historial de mensajes de chat con filtrado, ordenación y paginación
    • Obtener todos los mensajes disponibles mediante paginación @odata.nextLink
    • Enviar mensajes a chats existentes
    • Editar mensajes de chat enviados previamente
    • Eliminar suavemente mensajes de chat

✏️ Gestión de Mensajes

  • Editar y Eliminar
    • Actualizar (editar) mensajes enviados en chats y canales
    • Eliminar suavemente mensajes en chats y canales (se marcan como eliminados sin eliminación permanente)
    • Solo los remitentes de mensajes pueden actualizar/eliminar sus propios mensajes
    • Soporte para formato Markdown, menciones y niveles de importancia en las ediciones

📎 Medios y Adjuntos

  • Contenido Alojado

    • Descargar contenido alojado (imágenes, archivos) de mensajes de chat y canales
    • Acceder a imágenes en línea y adjuntos compartidos en conversaciones
    • Opcionalmente, guardar contenido alojado directamente en disco

  • Carga de Archivos

    • Cargar y enviar cualquier tipo de archivo (PDF, DOCX, XLSX, ZIP, imágenes, etc.) a canales y chats
    • Soporte para archivos grandes (>4 MB) mediante sesiones de carga reanudables
    • Las cargas en canales van a SharePoint y las cargas en chats van a OneDrive
    • Texto de mensaje opcional, nombre de archivo personalizado, formato y niveles de importancia

🔍 Búsqueda y Descubrimiento Avanzado

  • Búsqueda de Mensajes
    • Buscar en todos los canales y chats de Teams mediante la API de Búsqueda de Microsoft
    • Soporte para sintaxis KQL (Lenguaje de Consulta de Palabras Clave)
    • Filtrar por remitente, menciones, adjuntos, estado de lectura y rangos de fechas
    • Obtener mensajes recientes con opciones de filtrado avanzadas
    • Encontrar mensajes que mencionan al usuario actual

Soporte de Formato de Mensajes Enriquecidos

Las siguientes herramientas admiten formato de mensajes enriquecidos en canales y chats de Teams:

  • send_channel_message
  • send_chat_message
  • reply_to_channel_message
  • update_channel_message
  • update_chat_message
  • send_file_to_channel
  • send_file_to_chat

Opciones de Formato

Puedes especificar el parámetro format para controlar el formato del mensaje:

  • text (predeterminado): Texto plano
  • markdown: Formato Markdown (negrita, cursiva, listas, enlaces, código, etc.) convertido a HTML saneado

Cuando format se establece en markdown, el contenido del mensaje se convierte a HTML utilizando un analizador de Markdown seguro y se sanea para eliminar contenido potencialmente peligroso antes de enviarse a Teams.

Si format no se especifica, el mensaje se enviará como texto plano.

Ejemplo de Uso

{
  "teamId": "...",
  "channelId": "...",
  "message": "**Bold text** and _italic text_\n\n- List item 1\n- List item 2\n\n[Link](https://example.com)",
  "format": "markdown",
  "importance": "high"
}

{
  "chatId": "...",
  "message": "Simple plain text message",
  "format": "text"
}

Características de Seguridad

  • Saneamiento de HTML: Todo el contenido Markdown se convierte a HTML y se sanea para eliminar elementos potencialmente peligrosos (scripts, manejadores de eventos, etc.)
  • Etiquetas Permitidas: Solo se permiten etiquetas HTML seguras (p, strong, em, a, ul, ol, li, h1-h6, code, pre, etc.)
  • Atributos Seguros: Solo se permiten atributos seguros
  • Prevención de XSS: El contenido se sanea automáticamente para prevenir ataques de secuencias de comandos entre sitios

Características de Markdown Admitidas

  • Formato de texto: Negrita (**text**), cursiva (_text_), tachado (~~text~~)
  • Enlaces: [text](url)
  • Listas: Con viñetas (- item) y numeradas (1. item)
  • Código: Código en línea `code` y bloques de código delimitados
  • Encabezados: # H1 hasta ###### H6
  • Citas en bloque: > quoted text
  • Tablas: Tablas Markdown con estilo GitHub

Contenido Amigable para LLM

Los mensajes recuperados de la API de Microsoft Graph se devuelven como HTML sin procesar que contiene etiquetas específicas de Teams. Para hacer que este contenido sea más consumible para los asistentes de IA, las siguientes herramientas admiten la conversión automática de HTML a Markdown:

  • get_chat_messages
  • get_channel_messages
  • get_channel_message_replies
  • search_messages
  • get_my_mentions

Opciones de Formato de Contenido

Usa el parámetro contentFormat para controlar cómo se devuelve el contenido del mensaje:

  • markdown (predeterminado): Convierte el HTML de Teams a Markdown limpio, optimizado para el consumo de LLM
  • raw: Devuelve el HTML original de la API de Microsoft Graph

Qué se Convierte

Elemento HTMLSalida Markdown
<at id="0">Name</at> (mención de Teams)@Name (nombres de varias palabras fusionados usando metadatos de menciones)
<strong>text</strong>**text**
<em>text</em>*text*
<code>text</code>`texto`
<a href="url">text</a>[text](url)
<ul><li>item</li></ul>- item
<table>...</table>Tabla Markdown GFM
<attachment id="...">{attachment:id}
<systemEventMessage/>(eliminado)
<hr>---
&nbsp;, &amp;, etc.Decodificado a caracteres simples

Metadatos de Adjuntos

Los mensajes que contienen archivos adjuntos o imágenes en línea incluyen una matriz attachments en la respuesta con metadatos para cada adjunto (id, nombre, tipo de contenido, URL de contenido, URL de miniatura). Los marcadores en línea {attachment:id} en el contenido Markdown se correlacionan con las entradas de esta matriz, lo que permite a los consumidores identificar y descargar adjuntos mediante download_message_hosted_content o download_chat_hosted_content.

Ejemplo de Uso

{
  "chatId": "19:meeting_...",
  "limit": 10,
  "contentFormat": "markdown"
}

Para obtener el HTML original:

{
  "chatId": "19:meeting_...",
  "limit": 10,
  "contentFormat": "raw"
}

📦 Instalación

# Install dependencies
npm install

# Build the project
npm run build

# Set up authentication
npm run auth

🔧 Configuración

Requisitos Previos

  • Node.js 18+
  • Cuenta de Microsoft 365 con permisos apropiados
  • Permisos delegados de Microsoft Graph para los ámbitos a continuación

Permisos Requeridos de Microsoft Graph

Modo completo (predeterminado):

  • User.Read - Leer perfil de usuario
  • User.ReadBasic.All - Leer información básica del usuario
  • Team.ReadBasic.All - Leer información del equipo
  • Channel.ReadBasic.All - Leer información del canal
  • ChannelMessage.Read.All - Leer mensajes del canal
  • ChannelMessage.Send - Enviar mensajes y respuestas del canal
  • ChannelMessage.ReadWrite - Editar y eliminar mensajes del canal
  • Chat.Read - Leer mensajes de chat (incluidos mediante ámbitos de solo lectura)
  • Chat.ReadWrite - Crear y gestionar chats, enviar/editar/eliminar mensajes de chat (reemplaza a Chat.Read)
  • TeamMember.Read.All - Leer miembros del equipo
  • Files.ReadWrite.All - Requerido para cargas de archivos a canales y chats

Modo de solo lectura (TEAMS_MCP_READ_ONLY=true) — solo se solicitan estos ámbitos:

  • User.Read
  • User.ReadBasic.All
  • Team.ReadBasic.All
  • Channel.ReadBasic.All
  • ChannelMessage.Read.All
  • TeamMember.Read.All
  • Chat.Read

Modos de Autenticación

Acceso completo:

npx @floriscornel/teams-mcp@latest authenticate

Acceso de solo lectura:

npx @floriscornel/teams-mcp@latest authenticate --read-only

Inyección directa de token con un JWT de Microsoft Graph existente:

{
  "mcpServers": {
    "teams-mcp": {
      "command": "npx",
      "args": ["-y", "@floriscornel/teams-mcp@latest"],
      "env": {
        "AUTH_TOKEN": "<jwt-for-https://graph.microsoft.com>"
      }
    }
  }
}

Almacenamiento de Tokens

  • Los metadatos de autenticación se almacenan localmente en ~/.msgraph-mcp-auth.json
  • La caché de tokens se almacena localmente en ~/.teams-mcp-token-cache.json

🛠️ Uso

Iniciar el Servidor

# Development mode with hot reload
npm run dev

# Production mode
npm run build && node dist/index.js

# Start in read-only mode (disables all write tools)
TEAMS_MCP_READ_ONLY=true node dist/index.js

Comandos CLI

npx @floriscornel/teams-mcp@latest authenticate              # Authenticate with full scopes
npx @floriscornel/teams-mcp@latest authenticate --read-only  # Authenticate with read-only scopes
npx @floriscornel/teams-mcp@latest check                     # Check authentication status
npx @floriscornel/teams-mcp@latest logout                    # Clear authentication
npx @floriscornel/teams-mcp@latest auth                      # Alias for authenticate
npx @floriscornel/teams-mcp@latest                           # Start MCP server (default)

Variables de Entorno

  • TEAMS_MCP_READ_ONLY=true - Iniciar el servidor MCP en modo de solo lectura
  • AUTH_TOKEN=<jwt> - Usar un token de acceso de Microsoft Graph preexistente en lugar del inicio de sesión de MSAL

Modo de Solo Lectura

El servidor admite un modo de solo lectura que desactiva todas las operaciones de escritura (enviar mensajes, crear chats, cargar archivos, editar/eliminar mensajes) y solicita solo ámbitos de permiso de lectura a Microsoft Graph.

Habilitar el modo de solo lectura usando cualquiera de las siguientes opciones:

  • Variable de entorno: TEAMS_MCP_READ_ONLY=true
  • Indicador CLI: --read-only

Autenticar con ámbitos reducidos:

npx @floriscornel/teams-mcp@latest authenticate --read-only

Configuración del servidor MCP (solo lectura):

{
  "mcpServers": {
    "teams-mcp": {
      "command": "npx",
      "args": ["-y", "@floriscornel/teams-mcp@latest"],
      "env": {
        "TEAMS_MCP_READ_ONLY": "true"
      }
    }
  }
}

Cambio de modos: Al cambiar del modo de solo lectura al modo completo, el servidor detecta la discrepancia de ámbitos y te advierte que vuelvas a autenticarte:

npx @floriscornel/teams-mcp@latest authenticate

Herramientas de solo lectura (16): auth_status, get_current_user, search_users, get_user, list_teams, list_channels, get_channel_messages, get_channel_message_replies, list_team_members, search_users_for_mentions, download_message_hosted_content, list_chats, get_chat_messages, download_chat_hosted_content, search_messages, get_my_mentions

Herramientas de escritura desactivadas en modo de solo lectura (10): send_channel_message, reply_to_channel_message, update_channel_message, delete_channel_message, send_file_to_channel, send_chat_message, create_chat, update_chat_message, delete_chat_message, send_file_to_chat

Herramientas MCP Disponibles

Autenticación

  • auth_status - Verificar el estado de autenticación actual

Operaciones de Usuario

  • get_current_user - Obtener información del usuario autenticado
  • search_users - Buscar usuarios por nombre o correo electrónico
  • get_user - Obtener información detallada del usuario por ID o correo electrónico

Operaciones de Teams

  • list_teams - Listar los equipos a los que se ha unido el usuario
  • list_channels - Listar canales en un equipo específico
  • get_channel_messages - Recuperar mensajes de un canal de equipo con resúmenes de adjuntos y selección de formato de contenido
  • get_channel_message_replies - Obtener respuestas a un mensaje de canal específico
  • send_channel_message - Enviar un mensaje a un canal de equipo con menciones, importancia y adjuntos de imagen opcionales
  • reply_to_channel_message - Responder a un mensaje de canal existente
  • update_channel_message - Editar un mensaje o respuesta de canal enviado previamente
  • delete_channel_message - Eliminar suavemente un mensaje o respuesta de canal
  • list_team_members - Listar miembros de un equipo específico
  • search_users_for_mentions - Buscar miembros del equipo para @mencionar en mensajes
  • send_file_to_channel - Cargar un archivo local y enviarlo como mensaje a un canal

Operaciones de chat

  • list_chats - Listar los chats del usuario (1:1 y grupales)
  • get_chat_messages - Recuperar mensajes de un chat específico con paginación, filtros, ordenamiento y fetchAll
  • send_chat_message - Enviar un mensaje a un chat
  • create_chat - Crear un nuevo chat 1:1 o grupal
  • update_chat_message - Editar un mensaje de chat enviado anteriormente
  • delete_chat_message - Eliminar suavemente un mensaje de chat (soft delete)
  • send_file_to_chat - Subir un archivo local y enviarlo como mensaje a un chat

Operaciones de medios

  • download_message_hosted_content - Descargar contenido alojado (imágenes, archivos) de mensajes de canal
  • download_chat_hosted_content - Descargar contenido alojado (imágenes, archivos) de mensajes de chat

Operaciones de búsqueda

  • search_messages - Buscar en todos los mensajes de Teams usando sintaxis KQL
  • get_my_mentions - Encontrar mensajes recientes que mencionen al usuario actual

📋 Ejemplos

Autenticación

Primero, autentícate con Microsoft Graph:

# Full access (default)
npx @floriscornel/teams-mcp@latest authenticate

# Read-only (reduced permission scopes)
npx @floriscornel/teams-mcp@latest authenticate --read-only

Comprueba tu estado de autenticación:

npx @floriscornel/teams-mcp@latest check

Cierra sesión si es necesario:

npx @floriscornel/teams-mcp@latest logout

Ejemplo de paginación de chat

{
  "chatId": "19:meeting_...",
  "limit": 100,
  "fetchAll": true,
  "orderBy": "createdDateTime",
  "descending": true,
  "contentFormat": "markdown"
}

Mensaje de canal con menciones e imagen

{
  "teamId": "team-id",
  "channelId": "channel-id",
  "message": "Please review **today's update**",
  "format": "markdown",
  "importance": "high",
  "mentions": [
    {
      "mention": "alex.chen",
      "userId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "imageUrl": "https://example.com/status.png"
}

Ejemplo de subida de archivo

{
  "chatId": "19:meeting_...",
  "filePath": "/absolute/path/to/report.pdf",
  "message": "Please review the attached report",
  "format": "markdown"
}

Integración con Cursor/Claude

Este servidor MCP está diseñado para trabajar con asistentes de IA como Claude/Cursor/VS Code a través del Protocolo de Contexto de Modelo.

{
  "mcpServers": {
    "teams-mcp": {
      "command": "npx",
      "args": ["-y", "@floriscornel/teams-mcp@latest"]
    }
  }
}

🔒 Seguridad

  • Toda la autenticación se maneja mediante el flujo OAuth 2.0 de Microsoft o un token de Microsoft Graph proporcionado por el llamador
  • Soporte de token de actualización: Los tokens de acceso se renuevan automáticamente usando tokens de actualización en caché, por lo que no necesitas reautenticarte cada hora
  • La caché de tokens se almacena localmente en ~/.teams-mcp-token-cache.json
  • Los metadatos de autenticación se almacenan localmente en ~/.msgraph-mcp-auth.json
  • El contenido Markdown se sanitiza antes de enviar HTML a Teams
  • AUTH_TOKEN se valida para asegurar que apunta a https://graph.microsoft.com
  • No se registra ni expone información sensible
  • Sigue las mejores prácticas de seguridad de la API de Microsoft Graph

📝 Licencia

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

🤝 Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios
  4. Ejecuta la compilación, el linting y las pruebas
  5. Envía una solicitud de extracción (pull request)

📞 Soporte

Para problemas y preguntas:

  • Revisa los problemas existentes en GitHub
  • Revisa la documentación de la API de Microsoft Graph
  • Asegúrate de que la autenticación y los permisos estén configurados correctamente