Microsoft Entra ID MCP Server

Um servidor MCP Python para operações de diretório, usuário, grupo, dispositivo, login e segurança do Microsoft Entra ID (Azure AD) via Microsoft Graph.

GitHub
40
Experimente este MCPPatrocinado

Documentação

EntraID MCP Server (Microsoft Graph FastMCP)

Este projeto fornece um servidor FastMCP modular e orientado a recursos para interagir com a API do Microsoft Graph. Ele foi projetado para extensibilidade, manutenibilidade e segurança, suportando consultas avançadas para usuários, logs de entrada, status de MFA e usuários privilegiados.

Recursos

  • Estrutura de Recursos Modular:
    • Cada recurso (usuários, logs de entrada, MFA, etc.) é implementado em seu próprio módulo sob src/msgraph_mcp_server/resources/.
    • Fácil de estender com novos recursos (ex.: grupos, dispositivos).
  • Cliente Graph Centralizado:
    • Gerencia autenticação e inicialização do cliente.
    • Compartilhado por todos os módulos de recursos.
  • Operações Abrangentes de Usuário:
    • Pesquisar usuários por nome/e-mail.
    • Obter usuário por ID.
    • Listar todos os usuários privilegiados (membros de funções de diretório).
  • Gerenciamento Completo do Ciclo de Vida de Grupos e Associações:
    • Criar, ler, atualizar e excluir grupos.
    • Adicionar/remover membros e proprietários de grupos.
    • Pesquisar e listar grupos e membros de grupos.
  • Gerenciamento de Aplicativos e Principais de Serviço:
    • Listar, criar, atualizar e excluir aplicativos (registros de aplicativos).
    • Listar, criar, atualizar e excluir principais de serviço.
    • Visualizar atribuições de funções de aplicativo e permissões delegadas para aplicativos e principais de serviço.
  • Operações de Log de Entrada:
    • Consultar logs de entrada de um usuário nos últimos X dias.
  • Operações de MFA:
    • Obter status de MFA para um usuário.
    • Obter status de MFA para todos os membros de um grupo.
  • Gerenciamento de Senhas:
    • Redefinir senhas de usuários diretamente com senhas personalizadas ou geradas automaticamente de forma segura.
    • Opção para exigir alteração de senha no próximo login.
  • Auxiliar de Permissões:
    • Sugerir permissões apropriadas do Microsoft Graph para tarefas comuns.
    • Pesquisar e explorar permissões disponíveis do Graph.
    • Ajuda a implementar o princípio do menor privilégio, recomendando apenas as permissões necessárias.
  • Tratamento de Erros e Registro:
    • Tratamento consistente de erros e relatórios de progresso via contexto FastMCP.
    • Registro detalhado para solução de problemas.
  • Segurança:
    • .env e arquivos de segredos são excluídos do controle de versão.
    • Usa as melhores práticas da Microsoft para autenticação.

Estrutura do Projeto

src/msgraph_mcp_server/
├── auth/           # Authentication logic (GraphAuthManager)
├── resources/      # Resource modules (users, signin_logs, mfa, ...)
│   ├── users.py            # User operations (search, get by ID, etc.)
│   ├── signin_logs.py      # Sign-in log operations
│   ├── mfa.py              # MFA status operations
│   ├── permissions_helper.py # Graph permissions utilities and suggestions
│   ├── applications.py       # Application (app registration) operations
│   ├── service_principals.py # Service principal operations
│   └── ...                 # Other resource modules
├── utils/          # Core GraphClient and other ultilities tool, such as password generator..
├── server.py       # FastMCP server entry point (registers tools/resources)
├── __init__.py     # Package marker

Uso

1. Configuração

  • Clone o repositório.
  • Crie um arquivo config/.env com suas credenciais do Azure AD: 
    TENANT_ID=your-tenant-id
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
  • (Opcional) Configure autenticação baseada em certificado, se necessário.

2. Testes e Desenvolvimento

Você pode testar e desenvolver seu servidor MCP diretamente usando a CLI do FastMCP:

fastmcp dev '/path/to/src/msgraph_mcp_server/server.py'

Isso inicia um ambiente de desenvolvimento interativo com o MCP Inspector. Para mais informações e uso avançado, consulte a documentação do FastMCP.

3. Ferramentas Disponíveis

Ferramentas de Usuário

  • search_users(query, ctx, limit=10) — Pesquisar usuários por nome/e-mail
  • get_user_by_id(user_id, ctx) — Obter detalhes do usuário por ID
  • get_privileged_users(ctx) — Listar todos os usuários em funções de diretório privilegiadas
  • get_user_roles(user_id, ctx) — Obter todas as funções de diretório atribuídas a um usuário
  • get_user_groups(user_id, ctx) — Obter todos os grupos (incluindo associações transitivas) para um usuário

Ferramentas de Grupo

  • get_all_groups(ctx, limit=100) — Obter todos os grupos (com paginação)
  • get_group_by_id(group_id, ctx) — Obter um grupo específico pelo seu ID
  • search_groups_by_name(name, ctx, limit=50) — Pesquisar grupos por nome de exibição
  • get_group_members(group_id, ctx, limit=100) — Obter membros de um grupo pelo ID do grupo
  • create_group(ctx, group_data) — Criar um novo grupo (veja abaixo os campos de group_data)
  • update_group(group_id, ctx, group_data) — Atualizar um grupo existente (campos: displayName, mailNickname, description, visibility)
  • delete_group(group_id, ctx) — Excluir um grupo pelo seu ID
  • add_group_member(group_id, member_id, ctx) — Adicionar um membro (usuário, grupo, dispositivo, etc.) a um grupo
  • remove_group_member(group_id, member_id, ctx) — Remover um membro de um grupo
  • add_group_owner(group_id, owner_id, ctx) — Adicionar um proprietário a um grupo
  • remove_group_owner(group_id, owner_id, ctx) — Remover um proprietário de um grupo

Exemplo de Criação/Atualização de Grupo:

  • group_data para create_group e update_group deve ser um dicionário com chaves como:
    • displayName (obrigatório para criação)
    • mailNickname (obrigatório para criação)
    • description (opcional)
    • groupTypes (opcional, ex.: ["Unified"])
    • mailEnabled (opcional)
    • securityEnabled (opcional)
    • visibility (opcional, "Private" ou "Public")
    • owners (opcional, lista de IDs de usuários)
    • members (opcional, lista de IDs)
    • membershipRule (obrigatório para grupos dinâmicos)
    • membershipRuleProcessingState (opcional, "On" ou "Paused")

Consulte as docstrings de groups.py para mais detalhes sobre campos e comportamentos suportados.

Ferramentas de Log de Entrada

  • get_user_sign_ins(user_id, ctx, days=7) — Obter logs de entrada para um usuário

Ferramentas de MFA

  • get_user_mfa_status(user_id, ctx) — Obter status de MFA para um usuário
  • get_group_mfa_status(group_id, ctx) — Obter status de MFA para todos os membros de um grupo

Ferramentas de Dispositivos

  • get_all_managed_devices(filter_os=None) — Obter todos os dispositivos gerenciados (opcionalmente filtrar por SO)
  • get_managed_devices_by_user(user_id) — Obter todos os dispositivos gerenciados para um usuário específico

Ferramentas de Políticas de Acesso Condicional

  • get_conditional_access_policies(ctx) — Obter todas as políticas de acesso condicional
  • get_conditional_access_policy_by_id(policy_id, ctx) — Obter uma única política de acesso condicional pelo seu ID

Ferramentas de Log de Auditoria

  • get_user_audit_logs(user_id, days=30) — Obter todos os logs de auditoria de diretório relevantes para um usuário por user_id nos últimos N dias

Ferramentas de Gerenciamento de Senhas

  • reset_user_password_direct(user_id, password=None, require_change_on_next_sign_in=True, generate_password=False, password_length=12) — Redefinir a senha de um usuário com um valor específico ou gerar uma senha aleatória segura

Ferramentas de Auxílio de Permissões

  • suggest_permissions_for_task(task_category, task_name) — Sugerir permissões do Microsoft Graph para uma tarefa específica com base em mapeamentos comuns
  • list_permission_categories_and_tasks() — Listar todas as categorias e tarefas disponíveis para sugestões de permissões
  • get_all_graph_permissions() — Obter todas as permissões do Microsoft Graph diretamente da API do Microsoft Graph
  • search_permissions(search_term, permission_type=None) — Pesquisar permissões do Microsoft Graph por palavra-chave

Ferramentas de Aplicativos

  • list_applications(ctx, limit=100) — Listar todos os aplicativos (registros de aplicativos) no locatário, com paginação
  • get_application_by_id(app_id, ctx) — Obter um aplicativo específico pelo seu ID de objeto (inclui atribuições de funções de aplicativo e permissões delegadas)
  • create_application(ctx, app_data) — Criar um novo aplicativo (veja abaixo os campos de app_data)
  • update_application(app_id, ctx, app_data) — Atualizar um aplicativo existente (campos: displayName, signInAudience, tags, identifierUris, web, api, requiredResourceAccess)
  • delete_application(app_id, ctx) — Excluir um aplicativo pelo seu ID de objeto

Exemplo de Criação/Atualização de Aplicativo:

  • app_data para create_application e update_application deve ser um dicionário com chaves como:
    • displayName (obrigatório para criação)
    • signInAudience (opcional)
    • tags (opcional)
    • identifierUris (opcional)
    • web (opcional)
    • api (opcional)
    • requiredResourceAccess (opcional)

Ferramentas de Principal de Serviço

  • list_service_principals(ctx, limit=100) — Listar todos os principais de serviço no locatário, com paginação
  • get_service_principal_by_id(sp_id, ctx) — Obter um principal de serviço específico pelo seu ID de objeto (inclui atribuições de funções de aplicativo e permissões delegadas)
  • create_service_principal(ctx, sp_data) — Criar um novo principal de serviço (veja abaixo os campos de sp_data)
  • update_service_principal(sp_id, ctx, sp_data) — Atualizar um principal de serviço existente (campos: displayName, accountEnabled, tags, appRoleAssignmentRequired)
  • delete_service_principal(sp_id, ctx) — Excluir um principal de serviço pelo seu ID de objeto

Exemplo de Criação/Atualização de Principal de Serviço:

  • sp_data para create_service_principal e update_service_principal deve ser um dicionário com chaves como:
    • appId (obrigatório para criação)
    • accountEnabled (opcional)
    • tags (opcional)
    • appRoleAssignmentRequired (opcional)
    • displayName (opcional)

Exemplo de Recurso

  • greeting://{name} — Retorna uma saudação personalizada

Estendendo o Servidor

  • Adicione novos módulos de recursos sob resources/ (ex.: groups.py, devices.py).
  • Registre novas ferramentas em server.py usando o decorador @mcp.tool() do FastMCP.
  • Use o GraphClient compartilhado para todas as chamadas de API.

Segurança e Melhores Práticas

  • Nunca confirme segredos: .env e outros arquivos sensíveis são ignorados pelo git.
  • Use o menor privilégio: Conceda apenas as permissões necessárias do Microsoft Graph ao seu aplicativo do Azure AD.
  • Audite e monitore: Use a saída de registro para solução de problemas e monitoramento.

Permissões Necessárias da API do Graph

API / PermissãoTipoDescrição
AuditLog.Read.AllApplicationLer todos os dados de log de auditoria
AuthenticationContext.Read.AllApplicationLer todas as informações de contexto de autenticação
DeviceManagementManagedDevices.Read.AllApplicationLer dispositivos do Microsoft Intune
Directory.Read.AllApplicationLer dados de diretório
Group.Read.AllApplicationLer todos os grupos
GroupMember.Read.AllApplicationLer todas as associações de grupo
Group.ReadWrite.AllApplicationCriar, atualizar, excluir grupos; gerenciar membros e proprietários de grupos
Policy.Read.AllApplicationLer as políticas da sua organização
RoleManagement.Read.DirectoryApplicationLer todas as configurações de RBAC do diretório
User.Read.AllApplicationLer todos os perfis completos dos usuários
User-PasswordProfile.ReadWrite.AllApplicationPermissão menos privilegiada para atualizar a propriedade passwordProfile
UserAuthenticationMethod.Read.AllApplicationLer todos os métodos de autenticação dos usuários
Application.ReadWrite.AllApplicationCriar, atualizar e excluir aplicativos (registros de aplicativos) e principais de serviço

Nota: Group.ReadWrite.All é necessário para criação, atualização, exclusão de grupos e para adicionar/remover membros ou proprietários de grupos. Group.Read.All e GroupMember.Read.All são suficientes para consultas somente leitura de grupos e associações.

Avançado: Usando com Claude ou Cursor

Usando com Claude (Anthropic)

Para instalar e executar este servidor como uma ferramenta MCP do Claude, use:

fastmcp install '/path/to/src/msgraph_mcp_server/server.py' \
  --with msgraph-sdk --with azure-identity --with azure-core --with msgraph-core \
  -f /path/to/.env
  • Substitua /path/to/ pelo caminho real do seu projeto.
  • A flag -f aponta para o seu arquivo .env (nunca confirme segredos!).

Usando com Cursor

Adicione o seguinte ao seu .cursor/mcp.json (não inclua segredos reais no controle de versão):

{
  "EntraID MCP Server": {
    "command": "uv",
    "args": [
      "run",
      "--with", "azure-core",
      "--with", "azure-identity",
      "--with", "fastmcp",
      "--with", "msgraph-core",
      "--with", "msgraph-sdk",
      "fastmcp",
      "run",
      "/path/to/src/msgraph_mcp_server/server.py"
    ],
    "env": {
      "TENANT_ID": "<your-tenant-id>",
      "CLIENT_ID": "<your-client-id>",
      "CLIENT_SECRET": "<your-client-secret>"
    }
  }
}
  • Substitua /path/to/ e as variáveis de ambiente pelos seus valores reais.
  • Nunca confirme segredos reais no seu repositório!

Licença

MIT