Сервер 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 для аутентификации.

Related MCP server: ms-365-admin-mcp-server

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

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

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

1. Настройка

• Клонируйте репозиторий.

• Создайте файл config/.env с вашими учетными данными Azure AD:

  TENANT_ID=your-tenant-id
  CLIENT_ID=your-client-id
  CLIENT_SECRET=your-client-secret

• (Необязательно) При необходимости настройте аутентификацию на основе сертификатов.

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

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

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

Это запускает интерактивную среду разработки с 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, используйте:

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

• Замените /path/to/ на фактический путь к вашему проекту.

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

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

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

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

• Замените /path/to/ и переменные среды на ваши фактические значения.

• Никогда не храните в своем хранилище настоящие секреты!

Лицензия

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