Teams MCP

Interaja com o Microsoft Teams, usuários e dados organizacionais por meio da API do Microsoft Graph.

GitHub
131
Experimente este MCPPatrocinado

Documentação

Teams MCP

npm version npm downloads codecov License: MIT GitHub stars

Um servidor Model Context Protocol (MCP) que fornece integração perfeita com as APIs do Microsoft Graph, permitindo que assistentes de IA interajam com Microsoft Teams, usuários, chats, arquivos e dados organizacionais.

Teams MCP server

📦 Instalação

Para usar este servidor MCP no Cursor/Claude/VS Code, adicione a seguinte configuração:

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

🚀 Recursos

🔐 Autenticação

  • Fluxo de autenticação por código de dispositivo OAuth 2.0 com Microsoft Graph
  • Gerenciamento seguro de tokens, persistência de cache e renovação de token de atualização
  • Verificação de status de autenticação e suporte a logout
  • Modo somente leitura com escopos reduzidos
  • Suporte direto a AUTH_TOKEN para tokens de acesso do Microsoft Graph pré-emitidos

👥 Gerenciamento de Usuários

  • Obter informações do usuário atual
  • Pesquisar usuários por nome ou e-mail
  • Recuperar perfis de usuário detalhados
  • Acessar dados do diretório organizacional

🏢 Integração com Microsoft Teams

  • Gerenciamento de Equipes

    • Listar equipes das quais o usuário participa
    • Acessar detalhes e metadados da equipe

  • Operações de Canal

    • Listar canais dentro de equipes
    • Recuperar mensagens e respostas do canal
    • Enviar mensagens para canais de equipe
    • Responder a tópicos existentes do canal
    • Editar e excluir suavemente mensagens e respostas do canal
    • Suporte a níveis de importância de mensagem (normal, high, urgent)
    • Suporte a anexos de imagem inline via URL ou dados base64

  • Membros da Equipe

    • Listar membros da equipe e suas funções
    • Acessar informações de membros
    • Pesquisar usuários para @mentions

💬 Chat e Mensagens

  • Chats 1:1 e em Grupo
    • Listar chats do usuário
    • Criar novas conversas 1:1 ou em grupo
    • Recuperar histórico de mensagens do chat com filtragem, ordenação e paginação
    • Buscar todas as mensagens disponíveis via paginação @odata.nextLink
    • Enviar mensagens para chats existentes
    • Editar mensagens de chat enviadas anteriormente
    • Excluir suavemente mensagens de chat

✏️ Gerenciamento de Mensagens

  • Editar e Excluir
    • Atualizar (editar) mensagens enviadas em chats e canais
    • Excluir suavemente mensagens em chats e canais (marca como excluída sem remoção permanente)
    • Somente remetentes da mensagem podem atualizar/excluir suas próprias mensagens
    • Suporte a formatação Markdown, menções e níveis de importância em edições

📎 Mídia e Anexos

  • Conteúdo Hospedado

    • Baixar conteúdo hospedado (imagens, arquivos) de mensagens de chat e canal
    • Acessar imagens inline e anexos compartilhados em conversas
    • Opcionalmente, salvar conteúdo hospedado diretamente no disco

  • Upload de Arquivos

    • Enviar e enviar qualquer tipo de arquivo (PDF, DOCX, XLSX, ZIP, imagens, etc.) para canais e chats
    • Suporte a arquivos grandes (>4 MB) via sessões de upload retomáveis
    • Uploads de canal vão para o SharePoint e uploads de chat vão para o OneDrive
    • Texto de mensagem opcional, nome de arquivo personalizado, formatação e níveis de importância

🔍 Pesquisa Avançada e Descoberta

  • Pesquisa de Mensagens
    • Pesquisar em todos os canais e chats do Teams usando a API de Pesquisa da Microsoft
    • Suporte à sintaxe KQL (Keyword Query Language)
    • Filtrar por remetente, menções, anexos, estado de leitura e intervalos de datas
    • Obter mensagens recentes com opções avançadas de filtragem
    • Encontrar mensagens que mencionam o usuário atual

Suporte a Formatação Rica de Mensagens

As seguintes ferramentas suportam formatação rica de mensagens em canais e chats do 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

Opções de Formatação

Você pode especificar o parâmetro format para controlar a formatação da mensagem:

  • text (padrão): Texto simples
  • markdown: Formatação Markdown (negrito, itálico, listas, links, código, etc.) convertida para HTML sanitizado

Quando format está definido como markdown, o conteúdo da mensagem é convertido para HTML usando um parser Markdown seguro e sanitizado para remover conteúdo potencialmente perigoso antes de ser enviado ao Teams.

Se format não for especificado, a mensagem será enviada como texto simples.

Exemplo 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"
}

Recursos de Segurança

  • Sanitização de HTML: Todo o conteúdo Markdown é convertido para HTML e sanitizado para remover elementos potencialmente perigosos (scripts, manipuladores de eventos, etc.)
  • Tags Permitidas: Apenas tags HTML seguras são permitidas (p, strong, em, a, ul, ol, li, h1-h6, code, pre, etc.)
  • Atributos Seguros: Apenas atributos seguros são permitidos
  • Prevenção de XSS: O conteúdo é automaticamente sanitizado para prevenir ataques de cross-site scripting

Recursos Markdown Suportados

  • Formatação de texto: Negrito (**text**), itálico (_text_), tachado (~~text~~)
  • Links: [text](url)
  • Listas: Com marcadores (- item) e numeradas (1. item)
  • Código: Inline `code` e blocos de código cercados
  • Cabeçalhos: # H1 até ###### H6
  • Citações em bloco: > quoted text
  • Tabelas: Tabelas Markdown no estilo GitHub

Formato de Conteúdo Amigável para LLM

Mensagens recuperadas da API do Microsoft Graph são retornadas como HTML bruto contendo tags específicas do Teams. Para tornar esse conteúdo mais consumível por assistentes de IA, as seguintes ferramentas suportam conversão automática de HTML para Markdown:

  • get_chat_messages
  • get_channel_messages
  • get_channel_message_replies
  • search_messages
  • get_my_mentions

Opções de Formato de Conteúdo

Use o parâmetro contentFormat para controlar como o conteúdo da mensagem é retornado:

  • markdown (padrão): Converte HTML do Teams para Markdown limpo, otimizado para consumo por LLM
  • raw: Retorna o HTML original da API do Microsoft Graph

O Que é Convertido

Elemento HTMLSaída Markdown
<at id="0">Name</at> (menção do Teams)@Name (nomes com várias palavras mesclados usando metadados de menções)
<strong>text</strong>**text**
<em>text</em>*text*
<code>text</code>`text`
<a href="url">text</a>[text](url)
<ul><li>item</li></ul>- item
<table>...</table>Tabela Markdown GFM
<attachment id="...">{attachment:id}
<systemEventMessage/>(removido)
<hr>---
&nbsp;, &amp;, etc.Decodificado para caracteres simples

Metadados de Anexos

Mensagens que contêm anexos de arquivo ou imagens inline incluem um array attachments na resposta com metadados para cada anexo (id, name, contentType, contentUrl, thumbnailUrl). Os marcadores inline {attachment:id} no conteúdo Markdown se correlacionam com entradas neste array, permitindo que consumidores identifiquem e baixem anexos via download_message_hosted_content ou download_chat_hosted_content.

Exemplo de Uso

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

Para obter o HTML original:

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

📦 Instalação

# Install dependencies
npm install

# Build the project
npm run build

# Set up authentication
npm run auth

🔧 Configuração

Pré-requisitos

  • Node.js 18+
  • Conta Microsoft 365 com permissões apropriadas
  • Permissões delegadas do Microsoft Graph para os escopos abaixo

Permissões Obrigatórias do Microsoft Graph

Modo completo (padrão):

  • User.Read - Ler perfil do usuário
  • User.ReadBasic.All - Ler informações básicas do usuário
  • Team.ReadBasic.All - Ler informações da equipe
  • Channel.ReadBasic.All - Ler informações do canal
  • ChannelMessage.Read.All - Ler mensagens do canal
  • ChannelMessage.Send - Enviar mensagens e respostas do canal
  • ChannelMessage.ReadWrite - Editar e excluir mensagens do canal
  • Chat.Read - Ler mensagens de chat (incluídas via escopos somente leitura)
  • Chat.ReadWrite - Criar e gerenciar chats, enviar/editar/excluir mensagens de chat (substitui Chat.Read)
  • TeamMember.Read.All - Ler membros da equipe
  • Files.ReadWrite.All - Necessário para uploads de arquivos em canais e chats

Modo somente leitura (TEAMS_MCP_READ_ONLY=true) — apenas estes escopos são solicitados:

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

Modos de Autenticação

Acesso completo:

npx @floriscornel/teams-mcp@latest authenticate

Acesso somente leitura:

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

Injeção direta de token com um JWT existente do Microsoft Graph:

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

Armazenamento de Tokens

  • Os metadados de autenticação são armazenados localmente em ~/.msgraph-mcp-auth.json
  • O cache de tokens é armazenado localmente em ~/.teams-mcp-token-cache.json

🛠️ Uso

Iniciando o 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)

Variáveis de Ambiente

  • TEAMS_MCP_READ_ONLY=true - Iniciar o servidor MCP em modo somente leitura
  • AUTH_TOKEN=<jwt> - Usar um token de acesso existente do Microsoft Graph em vez do login MSAL

Modo Somente Leitura

O servidor suporta um modo somente leitura que desativa todas as operações de escrita (envio de mensagens, criação de chats, upload de arquivos, edição/exclusão de mensagens) e solicita apenas escopos de permissão de leitura do Microsoft Graph.

Ative o modo somente leitura usando qualquer um dos seguintes:

  • Variável de ambiente: TEAMS_MCP_READ_ONLY=true
  • Flag CLI: --read-only

Autentique com escopos reduzidos:

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

Configuração do servidor MCP (somente leitura):

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

Alternando modos: Ao alternar do modo somente leitura para o modo completo, o servidor detecta a incompatibilidade de escopos e avisa você para reautenticar:

npx @floriscornel/teams-mcp@latest authenticate

Ferramentas somente leitura (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

Ferramentas de escrita desativadas no modo somente leitura (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

Ferramentas MCP Disponíveis

Autenticação

  • auth_status - Verificar o status atual de autenticação

Operações de Usuário

  • get_current_user - Obter informações do usuário autenticado
  • search_users - Pesquisar usuários por nome ou e-mail
  • get_user - Obter informações detalhadas do usuário por ID ou e-mail

Operações de Equipes

  • list_teams - Listar equipes das quais o usuário participa
  • list_channels - Listar canais em uma equipe específica
  • get_channel_messages - Recuperar mensagens de um canal de equipe com resumos de anexos e seleção de formato de conteúdo
  • get_channel_message_replies - Obter respostas a uma mensagem específica do canal
  • send_channel_message - Enviar uma mensagem para um canal de equipe com menções, importância e anexos de imagem opcionais
  • reply_to_channel_message - Responder a uma mensagem existente do canal
  • update_channel_message - Editar uma mensagem ou resposta de canal enviada anteriormente
  • delete_channel_message - Excluir suavemente uma mensagem ou resposta de canal
  • list_team_members - Listar membros de uma equipe específica
  • search_users_for_mentions - Pesquisar membros da equipe para @mencionar em mensagens
  • send_file_to_channel - Enviar um arquivo local e enviá-lo como mensagem para um canal

Operações de Chat

  • list_chats - Lista os chats do usuário (1:1 e em grupo)
  • get_chat_messages - Recupera mensagens de um chat específico com paginação, filtros, ordenação e fetchAll
  • send_chat_message - Envia uma mensagem para um chat
  • create_chat - Cria um novo chat 1:1 ou em grupo
  • update_chat_message - Edita uma mensagem de chat enviada anteriormente
  • delete_chat_message - Exclui temporariamente uma mensagem de chat
  • send_file_to_chat - Envia um arquivo local e o envia como mensagem para um chat

Operações de Mídia

  • download_message_hosted_content - Baixa conteúdo hospedado (imagens, arquivos) de mensagens de canal
  • download_chat_hosted_content - Baixa conteúdo hospedado (imagens, arquivos) de mensagens de chat

Operações de Pesquisa

  • search_messages - Pesquisa em todas as mensagens do Teams usando sintaxe KQL
  • get_my_mentions - Encontra mensagens recentes que mencionam o usuário atual

📋 Exemplos

Autenticação

Primeiro, autentique-se com o Microsoft Graph:

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

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

Verifique seu status de autenticação:

npx @floriscornel/teams-mcp@latest check

Faça logout se necessário:

npx @floriscornel/teams-mcp@latest logout

Exemplo de Paginação de Chat

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

Mensagem de Canal com Menções e Imagem

{
  "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"
}

Exemplo de Envio de Arquivo

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

Integração com Cursor/Claude

Este servidor MCP foi projetado para funcionar com assistentes de IA como Claude/Cursor/VS Code por meio do Model Context Protocol.

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

🔒 Segurança

  • Toda a autenticação é tratada pelo fluxo OAuth 2.0 da Microsoft ou por um token do Microsoft Graph fornecido pelo chamador
  • Suporte a token de atualização: Os tokens de acesso são renovados automaticamente usando tokens de atualização em cache, então você não precisa reautenticar a cada hora
  • O cache de tokens é armazenado localmente em ~/.teams-mcp-token-cache.json
  • Os metadados de autenticação são armazenados localmente em ~/.msgraph-mcp-auth.json
  • O conteúdo Markdown é sanitizado antes de enviar HTML para o Teams
  • AUTH_TOKEN é validado para garantir que tenha como alvo https://graph.microsoft.com
  • Nenhum dado sensível é registrado ou exposto
  • Segue as práticas recomendadas de segurança da API do Microsoft Graph

📝 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes

🤝 Contribuição

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Execute build, linting e testes
  5. Envie um pull request

📞 Suporte

Para problemas e perguntas:

  • Verifique os problemas existentes no GitHub
  • Revise a documentação da API do Microsoft Graph
  • Garanta que a autenticação e as permissões estejam configuradas corretamente