Graph MCP

Um MCP para interagir com o Office 365 - Teams, e-mail, calendário.

GitHub
5

Documentação

Graph MCP

Graph MCP é um servidor MCP em Node.js que conecta Claude Code e Codex ao Microsoft Teams, Outlook (e-mail e calendário), reuniões online, OneDrive, usuários e presença por meio do Microsoft Graph. Ele roda localmente via stdio e requer Node.js 22 ou mais recente.

O que ele faz

Graph MCP expõe exatamente 127 ferramentas:

CategoriaFerramentas
AutenticaçãoVerificar status, entrar com navegador ou código de dispositivo, sair
Usuários e organizaçãoLer seu perfil, pesquisar usuários, consultar um gerente ou subordinados diretos
Pessoas e contatosPesquisa de pessoas classificada por relevância, listar, criar, atualizar ou excluir contatos do Outlook, listar pastas de contatos
PesquisaPesquisar mensagens do Teams, ou pesquisar e-mail, calendário, arquivos e Teams juntos em uma única consulta classificada
ConversasListar, obter ou criar conversas, ler, enviar, editar ou excluir mensagens, reagir a mensagens, renomear conversas, gerenciar membros, marcar como lida
Teams e canaisListar equipes, canais e membros, obter uma equipe ou seu canal principal, criar canais, ler, enviar, responder, editar ou excluir mensagens de canal, acessar a pasta do SharePoint de um canal
CalendárioListar calendários e eventos, obter, criar, atualizar, cancelar ou excluir eventos, recorrência, RSVP, disponibilidade, horários sugeridos para reuniões, ocorrências de séries, salas reserváveis, calendários compartilhados
E-mailListar, ler, pesquisar ou sincronizar por delta o e-mail, enviar, responder ou encaminhar com rascunhos, cópia oculta, importância e anexos, mover e arquivar, excluir, marcar como lido, sinalizar, categorizar, gerenciar pastas e regras de caixa de entrada, dicas de e-mail, caixas de correio compartilhadas
Configurações da caixa de correioLer configurações da caixa de correio, definir respostas automáticas, definir fuso horário e horário de trabalho
ReuniõesResolver um ID de reunião a partir de um evento de calendário, URL de participação ou conversa de reunião, buscar uma reunião por URL de participação ou ID numérico do convite, criar ou obter reuniões online com links de participação, relatórios de presença, transcrições e gravações
PresençaLer sua própria presença, a de outro usuário ou de uma equipe inteira, definir disponibilidade ou mensagem de status, limpar presença
TarefasListar listas e tarefas do To Do, criar, atualizar, concluir ou excluir tarefas, listar tarefas do Planner atribuídas
ArquivosNavegar, pesquisar ou resolver links para conteúdo do OneDrive e SharePoint, enviar, baixar como texto ou bytes base64, copiar, mover, excluir, versionar e compartilhar arquivos, gerenciar permissões, ler itens recentes e compartilhados, ler e escrever intervalos do Excel

Pré-requisitos

  • Node.js 22 ou mais recente.
  • Um registro de aplicativo do Microsoft Entra ID configurado como cliente público na plataforma Aplicativos móveis e desktop.
  • URI de redirecionamento http://localhost:3000/auth/callback.
  • Sem segredo de cliente. Graph MCP usa autenticação delegada de usuário.

Adicione estas permissões delegadas exatas ao registro do aplicativo:

  • offline_access
  • openid
  • profile
  • User.Read
  • User.ReadBasic.All
  • User.Read.All
  • Chat.Read
  • Chat.ReadWrite
  • ChatMember.ReadWrite
  • ChatMessage.Send
  • ChannelMessage.Read.All
  • ChannelMessage.Send
  • ChannelMessage.ReadWrite
  • Channel.Create
  • TeamMember.Read.All
  • Team.ReadBasic.All
  • Channel.ReadBasic.All
  • ChannelMember.Read.All
  • Calendars.ReadWrite
  • Calendars.Read.Shared
  • Calendars.ReadWrite.Shared
  • Place.Read.All
  • Mail.Read
  • Mail.ReadWrite
  • Mail.Send
  • MailboxSettings.ReadWrite
  • Mail.ReadWrite.Shared
  • Mail.Send.Shared
  • Presence.Read
  • Presence.Read.All
  • Presence.ReadWrite
  • OnlineMeetings.Read
  • OnlineMeetings.ReadWrite
  • OnlineMeetingArtifact.Read.All
  • OnlineMeetingTranscript.Read.All
  • OnlineMeetingRecording.Read.All
  • Files.ReadWrite.All
  • Sites.Read.All
  • People.Read
  • Contacts.ReadWrite
  • Tasks.ReadWrite

Algumas organizações exigem consentimento do administrador para uma ou mais permissões. Use o menor privilégio que sua implantação precisar e siga o processo de aprovação da sua organização.

Instalação

Plugin do Claude Code

Este repositório é em si um marketplace de plugins, então o Claude Code pode instalá-lo diretamente do GitHub:

claude plugin marketplace add JustStas/Graph-MCP --scope user
claude plugin install graph-mcp@graph-mcp --scope user

A mesma coisa funciona dentro de uma sessão do Claude Code com /plugin marketplace add JustStas/Graph-MCP followed by /plugin install graph-mcp@graph-mcp.

O Claude clona o repositório no cache do marketplace, valida .claude-plugin/marketplace.json e instala o plugin autocontido no cache de plugins. O servidor MCP inicia a partir do pacote do plugin instalado, então não é necessário checkout do código-fonte. Para obter um novo lançamento, execute os dois comandos novamente.

Para desenvolvimento de plugins, um checkout local pode ser adicionado da mesma forma por caminho em vez de owner/repo:

claude plugin marketplace add /absolute/path/to/Graph-MCP --scope user
claude plugin install graph-mcp@graph-mcp --scope user

Plugin do Codex

O Codex aceita a mesma fonte de marketplace do GitHub:

codex plugin marketplace add JustStas/Graph-MCP --json
codex plugin add graph-mcp@personal --json

codex plugin marketplace add aceita um caminho local, owner/repo[@ref] ou uma URL Git HTTPS ou SSH, e --ref fixa uma tag ou branch específica. O manifesto do Codex inicia ./dist/graph-mcp.js relativo à raiz do plugin instalado, então não é necessário checkout do código-fonte.

Para desenvolvimento de plugins, aponte para um checkout local:

codex plugin marketplace add /absolute/path/to/Graph-MCP --json
codex plugin add graph-mcp@personal --json

npm

Instale o pacote público com escopo globalmente:

npm install --global @juststas/graph-mcp
graph-mcp setup

O pacote npm tem escopo JustStas, mas o executável instalado permanece graph-mcp. Invocar graph-mcp sem argumentos inicia o servidor MCP via stdio.

Checkout do código-fonte

npm ci
npm run build
node dist/cli.js setup

Em seguida, registre o ponto de entrada compilado com seu host:

claude mcp add graph-mcp -- node /absolute/path/to/Graph-MCP/dist/cli.js
codex mcp add graph-mcp -- node /absolute/path/to/Graph-MCP/dist/cli.js

Configuração inicial e autenticação

setup solicita o ID do Cliente e o ID do Locatário do aplicativo Entra e os salva em ~/.graph-mcp/config.json. O ID do Cliente e o ID do Locatário são identificadores, não segredos. O comando de configuração não realiza login.

Para um plugin instalado, use a habilidade de configuração incluída e seu comando específico do host:

  • Claude Code: node "${CLAUDE_PLUGIN_ROOT}/dist/graph-mcp.js" setup
  • Codex: resolva a raiz do plugin instalado a partir de skills/setup/SKILL.md, mude para esse diretório e execute node "./dist/graph-mcp.js" setup

Após a configuração, chame graph_auth_login. O login PKCE no navegador é o padrão e abre um callback de loopback local na URI de redirecionamento configurada. Se um navegador ou callback de loopback não estiver disponível, chame graph_auth_login com method: "device_code" e siga as instruções de verificação da Microsoft retornadas.

Nunca cole um segredo de cliente, token de acesso, token de atualização, código de autorização, código MFA ou outras credenciais em uma conversa. Graph MCP não precisa de um segredo de cliente.

Configuração

Para ID do Cliente e ID do Locatário, as variáveis de ambiente têm precedência sobre ~/.graph-mcp/config.json, que tem precedência sobre os padrões internos. O comando de configuração persiste apenas esses dois identificadores. Outras opções são substituições apenas por ambiente dos padrões internos.

VariávelObrigatóriaPadrãoDescrição
AZURE_CLIENT_IDSimsalvo azureClientId, depois vazioID do aplicativo de cliente público do Entra
AZURE_TENANT_IDNãosalvo azureTenantId, depois commonID do locatário ou common
GRAPH_REDIRECT_URINãohttp://localhost:3000/auth/callbackDeve corresponder exatamente ao registro do aplicativo
GRAPH_TOKEN_ENCRYPTION_KEYNãochave local geradaMaterial explícito da chave de criptografia de token
GRAPH_TOKEN_REFRESH_BUFFERNão300Atualizar tokens de acesso este número de segundos antes da expiração
GRAPH_RATE_LIMIT_MAX_REQUESTSNão10000Limite de solicitações em janela deslizante
GRAPH_RATE_LIMIT_WINDOWNão600Duração da janela deslizante em segundos
GRAPH_DEBUGNãofalseHabilitar registro de diagnóstico em stderr

Opções de inteiros positivos rejeitam zero, negativos, decimais e valores malformados. Valores booleanos aceitam true, false, 1, 0, yes, no, on ou off.

Armazenamento de tokens e migração do Python

O servidor Node criptografa tokens com AES-256-GCM e os armazena em ~/.graph-mcp:

  • tokens-v2.enc — dados de token criptografados
  • .key-v2 — chave de criptografia local gerada quando nenhuma chave de ambiente é fornecida

O runtime Python anterior usava tokens.enc e .key. A versão 0.6.0 deliberadamente não lê, sobrescreve ou exclui esses arquivos legados porque os formatos de texto cifrado diferem. Após atualizar do lançamento Python, autentique-se uma vez com graph_auth_login; o servidor Node então cria seus arquivos de token versionados separados. Os arquivos de token Python existentes permanecem intactos e podem ser removidos posteriormente de acordo com sua política de segurança local.

Os tokens de acesso são atualizados automaticamente antes da expiração. graph_auth_logout limpa o estado de token do Node; ele não modifica os arquivos Python legados.

Formatação de mensagens e e-mails

As ferramentas de mensagens do Teams (graph_send_chat_message, graph_send_channel_message e graph_reply_to_channel_message) e as ferramentas de e-mail de saída (graph_send_mail e graph_reply_mail) usam o modo HTML por padrão. Quando is_html=true, passe HTML explícito; Markdown não é convertido automaticamente.

<p><strong>Status update</strong></p>
<ul>
  <li>Use <code>&lt;strong&gt;</code> for bold text.</li>
  <li>Use <code>&lt;pre&gt;&lt;code&gt;</code> for multi-line code blocks.</li>
</ul>

Use is_html=false para texto simples exato. Menções podem usar dados brutos do Graph ou esta forma simplificada, emparelhada com a tag <at id="0">Jane Smith</at> correspondente no corpo HTML:

[
  {
    "name": "Jane Smith",
    "user_id": "ef1c916a-3135-4417-ba27-8eb7bd084193"
  }
]

Desenvolvimento e verificação

Instale as dependências bloqueadas e execute o pipeline completo de verificação do Node:

npm ci
npm run verify

Comandos individuais úteis:

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npm run validate:versions
npm run validate:package
npx vitest run tests/plugin-install-smoke.test.ts

Validação de plugin e lançamento:

claude plugin validate --strict plugins/graph-mcp
claude plugin validate --strict .
python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/plugin-creator/scripts/validate_plugin.py" plugins/graph-mcp
node scripts/test-plugin-install.mjs
npm pack --json --dry-run

O validador do Codex é uma ferramenta de lançamento fornecida pela habilidade plugin-creator do Codex; Python não é necessário para compilar, testar ou executar o Graph MCP em si. Antes de publicar, verifique se o pacote, o manifesto do Claude e o manifesto do Codex correspondem à versão do lançamento alvo, o pacote de plugin confirmado está atualizado, ambos os plugins instalados expõem exatamente 127 ferramentas e a árvore de trabalho está limpa.

Procedimento de lançamento

Os lançamentos do Graph MCP usam o pacote npm público @juststas/graph-mcp; não há etapa de lançamento Python/PyPI. A versão 0.6.0 concluiu a migração para Node, mas não foi publicada no npm porque o npm rejeitou o nome graph-mcp@0.6.0 sem escopo como muito semelhante ao pacote graphmcp existente. A versão 0.6.1 é o primeiro lançamento npm com escopo.

Lançamentos normais

  1. Atualize package.json, package-lock.json, ambos os manifestos de plugin, metadados de runtime, CHANGELOG.md e o pacote de plugin confirmado para uma versão.
  2. Execute npm ci, npm run verify, node scripts/test-plugin-install.mjs e npm pack --json --dry-run a partir de uma árvore de trabalho limpa.
  3. Mescle o pull request revisado em main. Um administrador do repositório então cria a tag anotada v<version> no commit mesclado por meio do conjunto de regras obrigatório de autoridade de tags de lançamento; o conjunto de regras de imutabilidade separado sem bypass bloqueia atualização ou exclusão posterior.
  4. Publique o GitHub Release correspondente. O gatilho do workflow é release: types: [published].
  5. O job de pacote instala dependências bloqueadas, executa npm run verify e prepara o tarball exato sem permissão OIDC.
  6. O job de publicação roda no ambiente GitHub npm e é o único job que recebe permissão OIDC. Ele baixa um artefato somente de dados contendo o tarball e metadados, faz checkout do seu helper confiável em github.workflow_sha, vincula a tag esperada diretamente ao evento de lançamento, valida o manifesto JSON dry-run do npm para o snapshot privado exato e usa npm Trusted Publishing. Ele não tem NODE_AUTH_TOKEN ou segredo npm.
  7. Verifique o workflow, a versão npm, dist.integrity, a versão da CLI instalada e o inventário MCP de 127 ferramentas.

Reexecuções de workflow são idempotentes. Se a versão já existir, o workflow só é bem-sucedido quando o dist.integrity do npm for igual ao tarball preparado. Uma integridade diferente falha e exige uma nova versão de patch.

Bootstrap inicial do pacote com escopo

O npm exige que um pacote exista antes que o Trusted Publishing possa ser configurado. Faça o bootstrap do primeiro lançamento com escopo nesta ordem:

  1. Verifique o merge de main e, em seguida, ative o conjunto de regras de autoridade de administrador v*.
  2. Audite o inventário exato de tags históricas e a ancestralidade, exija o blob exato do workflow histórico do PyPI na allowlist onde esperado e exija que o novo auxiliar de release esteja ausente em todos os lugares.
  3. Ative o conjunto de regras de imutabilidade separado, sem bypass.
  4. Crie a tag anotada v0.6.1 somente depois que essas portas passarem.
  5. Execute publish.yml a partir de main com prepare_only habilitado e inspecione o artefato preparado.
  6. Valide o nome de arquivo exato, o status de arquivo regular, os digests SHA-512 e SHA-1 e o manifesto JSON do dry-run do npm. Publique esse mesmo snapshot privado uma vez com a 2FA interativa do mantenedor, registro npmjs explícito, tag latest, scripts de ciclo de vida desabilitados e acesso público; em seguida, verifique a versão e a integridade do registro.
  7. Revertifique ambos os conjuntos de regras de tags de release.
  8. Crie o ambiente do GitHub npm.
  9. Adicione políticas de ambiente tipadas separadas para a branch main e a tag v*.
  10. Verifique ambos os conjuntos de regras e ambas as políticas de ambiente tipadas.
  11. Configure o Trusted Publishing do npm:
npx --yes npm@11.15.0 trust github @juststas/graph-mcp \
  --file publish.yml \
  --repo JustStas/Graph-MCP \
  --env npm \
  --allow-publish

Verifique o repositório salvo, o nome do arquivo do workflow, o ambiente e a permissão de publicação e, em seguida, defina o acesso de publicação do npm para exigir 2FA e desautorizar tokens tradicionais.

O bootstrap manual 0.6.1 não usa OIDC nem proveniência, e seu workflow de release com correspondência de integridade é um no-op que não testa a troca OIDC. A versão 0.6.2 é a primeira publicação OIDC real e verificação de proveniência.

Recuperação

Use workflow_dispatch a partir de main com uma tag protegida existente para reexecutar a publicação. Use prepare_only quando apenas o tarball verificado for necessário. Os conjuntos de regras de tags de release proíbem mover ou excluir tags v* publicadas. Nunca sobrescreva uma versão do npm; recupere-se de uma publicação ruim com um novo patch release.

Arquitetura e comportamento em tempo de execução

Claude Code or Codex  --stdio-->  Graph MCP  --HTTPS-->  Microsoft Graph API
                                      |
                                ~/.graph-mcp/
                                  config.json
                                  tokens-v2.enc
                                  .key-v2
  • A autenticação usa OAuth 2.0 Authorization Code com PKCE ou device code.
  • A atualização do token de acesso é serializada para que chamadas Graph concorrentes compartilhem uma única atualização.
  • As solicitações Graph usam timeouts limitados, limitação de taxa com janela deslizante e comportamento de nova tentativa exponencial que honra Retry-After em respostas limitadas.
  • A saída do protocolo MCP é gravada em stdout; os diagnósticos são gravados em stderr.

Solução de problemas

Aprovação necessária durante o login

Confirme se as permissões delegadas exatas acima estão presentes e se o consentimento de administrador necessário foi concedido.

403 Forbidden para uma ferramenta

O endpoint pode precisar de uma permissão delegada ou consentimento de administrador não disponível para o usuário conectado. Verifique a permissão da ferramenta e a política da sua organização.

Callback do navegador indisponível

Chame graph_auth_login com method: "device_code" e conclua o login na URL de verificação da Microsoft.

Configuração alterada, mas o host ainda usa valores antigos

Reinicie o servidor MCP ou o host para que o processo recarregue config.json e seu ambiente. As variáveis de ambiente substituem os valores salvos de Client ID e Tenant ID.

Atualizado da versão Python e parece desconectado

Isso é esperado uma vez. Execute graph_auth_login; o runtime Node cria tokens-v2.enc e .key-v2 sem alterar os arquivos antigos tokens.enc e .key.

Aviso legal

Este projeto é um esforço independente de código aberto e não é afiliado, endossado ou patrocinado pela Microsoft Corporation. Microsoft, Microsoft Teams, Outlook, Microsoft 365, Microsoft Graph e Azure são marcas registradas do grupo de empresas Microsoft.

Este software é fornecido "como está", sem garantia de qualquer tipo. Use por sua conta e risco. Os autores não aceitam responsabilidade por danos, perda de dados ou problemas de segurança decorrentes do seu uso. Você é responsável por cumprir as políticas da sua organização e os Termos de Uso da API da Microsoft.

Este software acessa os serviços da Microsoft em seu nome usando suas próprias credenciais e registro de aplicativo. Os dados recuperados do Microsoft Graph (incluindo e-mails, mensagens, eventos de calendário, reuniões e arquivos) são passados ao modelo que invocou a ferramenta. Siga as BP e os requisitos da sua organização de tratamento de dados, retenção e uso aceitável ao usar modelos de IA hospedados na nuvem.

Licença

MIT — veja LICENSE.