EntraID MCP Server

Сервер EntraID MCP (Microsoft Graph FastMCP)

Этот проект предоставляет модульный, ресурсоориентированный сервер FastMCP для взаимодействия с Microsoft Graph API. Он разработан для расширяемости, удобства обслуживания и безопасности, поддерживая расширенные запросы для пользователей, журналы входа, статус MFA и привилегированных пользователей.

Функции

• Модульная структура ресурсов:
  • Каждый ресурс (пользователи, журналы входа, MFA и т. д.) реализован в собственном модуле в src/msgraph_mcp_server/resources/ .
  • Легко расширяется за счет новых ресурсов (например, групп, устройств).
• Централизованный графический клиент:
  • Выполняет аутентификацию и инициализацию клиента.
  • Используется всеми модулями ресурсов.
• Комплексные пользовательские операции:
  • Поиск пользователей по имени/адресу электронной почты.
  • Получить пользователя по идентификатору.
  • Вывести список всех привилегированных пользователей (членов роли каталога).
• Полный жизненный цикл группы и управление членством:
  • Создание, чтение, обновление и удаление групп.
  • Добавлять/удалять участников и владельцев групп.
  • Поиск и составление списка групп и участников групп.
• Управление принципами подачи заявок и обслуживания:
  • Перечисление, создание, обновление и удаление приложений (регистрация приложений).
  • Перечисление, создание, обновление и удаление принципалов служб.
  • Просматривайте назначения ролей приложений и делегированные разрешения как для приложений, так и для субъектов-служб.
• Операции журнала входа:
  • Запросить журналы входа пользователя за последние X дней.
• Операции МИД:
  • Получить статус MFA для пользователя.
  • Получите статус MFA для всех членов группы.
• Управление паролями:
  • Сбрасывайте пароли пользователей напрямую, используя пользовательские или автоматически сгенерированные безопасные пароли.
  • Возможность запроса смены пароля при следующем входе в систему.
• Помощник по разрешениям:
  • Предложите соответствующие разрешения Microsoft Graph для выполнения общих задач.
  • Поиск и изучение доступных разрешений Graph.
  • Помогает реализовать принцип наименьших привилегий, рекомендуя только необходимые разрешения.
• Обработка ошибок и ведение журнала:
  • Последовательная обработка ошибок и отчетность о ходе выполнения через контекст FastMCP.
  • Подробное ведение журнала для устранения неполадок.
• Безопасность:
  • Файлы .env и secret исключены из контроля версий.
  • Использует лучшие практики Microsoft для аутентификации.

Структура проекта

Использование

1. Настройка

• Клонируйте репозиторий.
• Создайте файл config/.env с вашими учетными данными Azure AD:
  TENANT_ID=your-tenant-id CLIENT_ID=your-client-id CLIENT_SECRET=your-client-secret
• (Необязательно) При необходимости настройте аутентификацию на основе сертификатов.

2. Тестирование и разработка

Вы можете тестировать и разрабатывать свой сервер MCP напрямую, используя FastMCP CLI:

Это запускает интерактивную среду разработки с MCP Inspector. Для получения дополнительной информации и расширенного использования см. документацию FastMCP .

3. Доступные инструменты

Пользовательские инструменты

• search_users(query, ctx, limit=10) — Поиск пользователей по имени/адресу электронной почты
• get_user_by_id(user_id, ctx) — Получить данные пользователя по ID
• get_privileged_users(ctx) — Список всех пользователей в привилегированных ролях каталога
• get_user_roles(user_id, ctx) — Получить все роли каталога, назначенные пользователю
• get_user_groups(user_id, ctx) — Получить все группы (включая транзитивное членство) для пользователя

Групповые инструменты

• get_all_groups(ctx, limit=100) — Получить все группы (с разбиением на страницы)
• get_group_by_id(group_id, ctx) — Получить определенную группу по ее идентификатору
• search_groups_by_name(name, ctx, limit=50) — Поиск групп по отображаемому имени
• get_group_members(group_id, ctx, limit=100) — Получить участников группы по идентификатору группы
• create_group(ctx, group_data) — Создать новую группу (поля group_data см. ниже)
• update_group(group_id, ctx, group_data) — Обновить существующую группу (поля: displayName, mailNickname, description, visible)
• delete_group(group_id, ctx) — Удалить группу по ее идентификатору
• add_group_member(group_id, member_id, ctx) — Добавить участника (пользователя, группу, устройство и т. д.) в группу
• remove_group_member(group_id, member_id, ctx) — Удалить участника из группы
• add_group_owner(group_id, owner_id, ctx) — Добавить владельца в группу
• remove_group_owner(group_id, owner_id, ctx) — Удалить владельца из группы

Пример создания/обновления группы:

• group_data для create_group и update_group должен быть словарем с такими ключами, как:
  • displayName (требуется для создания)
  • mailNickname (требуется для создания)
  • description (необязательно)
  • groupTypes (необязательно, например, ["Unified"] )
  • mailEnabled (необязательно)
  • securityEnabled (необязательно)
  • visibility (необязательно, «Частная» или «Публичная»)
  • owners (необязательно, список идентификаторов пользователей)
  • members (необязательно, список идентификаторов)
  • membershipRule (обязательно для динамических групп)
  • membershipRuleProcessingState (необязательно, «Вкл.» или «Приостановлено»)

Более подробную информацию о поддерживаемых полях и поведении см. в строках документации groups.py

Инструменты для входа в систему

• get_user_sign_ins(user_id, ctx, days=7) — Получить журналы входа для пользователя

Инструменты МФА

• get_user_mfa_status(user_id, ctx) — Получить статус MFA для пользователя
• get_group_mfa_status(group_id, ctx) — Получить статус MFA для всех участников группы

Инструменты устройства

• get_all_managed_devices(filter_os=None) — Получить все управляемые устройства (опционально фильтровать по ОС)
• get_managed_devices_by_user(user_id) — Получить все управляемые устройства для определенного пользователя

Инструменты политики условного доступа

• get_conditional_access_policies(ctx) — Получить все политики условного доступа
• get_conditional_access_policy_by_id(policy_id, ctx) — Получить одну политику условного доступа по ее идентификатору

Инструменты журнала аудита

• get_user_audit_logs(user_id, days=30) — Получить все соответствующие журналы аудита каталога для пользователя по user_id за последние N дней

Инструменты управления паролями

• reset_user_password_direct(user_id, password=None, require_change_on_next_sign_in=True, generate_password=False, password_length=12) — Сбросить пароль пользователя с определенным значением пароля или сгенерировать безопасный случайный пароль

Вспомогательные инструменты по правам доступа

• suggest_permissions_for_task(task_category, task_name) — предлагает разрешения Microsoft Graph для определенной задачи на основе общих сопоставлений
• list_permission_categories_and_tasks() — Список всех доступных категорий и задач для предложений разрешений
• get_all_graph_permissions() — получить все разрешения Microsoft Graph напрямую из API Microsoft Graph
• search_permissions(search_term, permission_type=None) — Поиск разрешений Microsoft Graph по ключевому слову

Инструменты для применения

• list_applications(ctx, limit=100) — Список всех приложений (регистраций приложений) в клиенте с разбиением на страницы
• get_application_by_id(app_id, ctx) — Получить определенное приложение по его идентификатору объекта (включая назначения ролей приложения и делегированные разрешения)
• create_application(ctx, app_data) — Создать новое приложение (поля app_data см. ниже)
• update_application(app_id, ctx, app_data) — Обновление существующего приложения (поля: displayName, signInAudience, tags, identifierUris, web, api, requiredResourceAccess)
• delete_application(app_id, ctx) — Удалить приложение по его идентификатору объекта

Пример создания/обновления приложения:

• app_data для create_application и update_application должен быть словарем с такими ключами, как:
  • displayName (требуется для создания)
  • signInAudience (необязательно)
  • tags (необязательно)
  • identifierUris (необязательно)
  • web (необязательно)
  • api (необязательно)
  • requiredResourceAccess (необязательно)

Инструменты для руководства службой

• list_service_principals(ctx, limit=100) — Список всех принципалов служб в клиенте с разбиением на страницы
• get_service_principal_by_id(sp_id, ctx) — Получить определенный принципал-службу по его идентификатору объекта (включая назначения ролей приложений и делегированные разрешения)
• create_service_principal(ctx, sp_data) — создание нового принципала службы (поля sp_data см. ниже)
• update_service_principal(sp_id, ctx, sp_data) — обновление существующего принципала службы (поля: displayName, accountEnabled, tags, appRoleAssignmentRequired)
• delete_service_principal(sp_id, ctx) — Удалить принципал-службу по его идентификатору объекта

Пример создания/обновления принципала службы:

• sp_data для create_service_principal и update_service_principal должен быть словарем с такими ключами, как:
  • appId (требуется для создания)
  • accountEnabled (необязательно)
  • tags (необязательно)
  • appRoleAssignmentRequired (необязательно)
  • displayName (необязательно)

Пример ресурса

• greeting://{name} — Возвращает персонализированное приветствие

Расширение сервера

• Добавьте новые модули ресурсов в resources/ (например, groups.py , devices.py ).
• Зарегистрируйте новые инструменты в server.py с помощью декоратора FastMCP @mcp.tool() .
• Используйте общий GraphClient для всех вызовов API.

Безопасность и передовой опыт

• Никогда не передавайте секреты: .env и другие конфиденциальные файлы игнорируются git.
• Используйте минимальные привилегии: предоставьте только необходимые разрешения Microsoft Graph для вашего приложения Azure AD.
• Аудит и мониторинг: используйте выходные данные журнала для устранения неполадок и мониторинга.

Требуемые разрешения API Graph

Примечание: Group.ReadWrite.All требуется для создания, обновления, удаления группы и для добавления/удаления членов группы или владельцев. Group.Read.All и GroupMember.Read.All достаточны для запросов на чтение и членство в группе.

Дополнительно: использование с Клодом или Курсором

Использование с Клодом (антропный)

Чтобы установить и запустить этот сервер как инструмент Claude MCP, используйте:

• Замените /path/to/ на фактический путь к вашему проекту.
• Флаг -f указывает на ваш файл .env (никогда не передавайте секреты!).

Использование с курсором

Добавьте следующее в ваш .cursor/mcp.json ( не включайте фактические секреты в систему контроля версий):

• Замените /path/to/ и переменные среды на ваши фактические значения.
• Никогда не храните в своем хранилище настоящие секреты!

Лицензия

Массачусетский технологический институт