entraadm-mcp

Английский | 日本語

MCP-сервер для разбора журналов входа и аудита Microsoft Entra ID. Только чтение.

Почему это вместо официального Microsoft MCP Server for Enterprise

Microsoft поставляет официальный MCP Server for Enterprise для данных Entra ID. Он хорошо подходит для интерактивного администратора за клавиатурой и не подходит для автоматического бота разбора журналов:

• Только делегированная аутентификация. Официальный сервер не поддерживает аутентификацию только для приложения (client credentials), поэтому он не может работать без головы за служебной учётной записью. entraadm-mcp создан для этого случая: только приложение в продакшене, с делегированным (az login) запасным вариантом для локальной разработки.

• Универсальный инструмент запросов к Graph, а не фиксированный набор инструментов. Официальный сервер предоставляет один инструмент, который позволяет модели выполнять произвольные вызовы GET/обнаружения схемы к Microsoft Graph. Это гибко для человека, но неудобно для размещения за списком разрешений для автоматического профиля разбора. entraadm-mcp вместо этого предоставляет семь фиксированных инструментов только для чтения.

• Нет перевода AADSTS. Сбои входа возвращаются в виде необработанных кодов ошибок; для разбора всё ещё нужна справочная таблица. entraadm-mcp аннотирует каждый сбой входа с указанием фактического значения кода.

• Нет агрегации между запросами. Сам Microsoft Graph не может фильтровать входы по status/errorCode на стороне сервера и не имеет встроенного представления для перебора паролей. signin_failure_stats агрегирует на стороне клиента и помечает IP-адреса с неудачными входами против многих разных пользователей — это тот паттерн, который умная блокировка Entra для каждой учётной записи сама по себе не ловит.

Related MCP server: Microsoft Graph MCP Server

Инструменты

Каждый инструмент доступен только для чтения. Операции записи (разблокировка учётной записи, сброс пароля, отзыв сеанса) выходят за рамки этого сервера.

Модель аутентификации

Два режима аутентификации, выбираемые в зависимости от того, какие переменные окружения установлены:

Установка одной или двух из трёх переменных app-only является ошибкой конфигурации, и сервер отказывается запускаться, а не молча переключается на другой режим аутентификации, чем предполагалось.

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

Отсутствующее разрешение никогда не приводит к сбою инструмента. Оно понижает этот инструмент (или это одно поле) до {"error": "...", "missing_permission": "..."} с понятным объяснением того, какая роль или разрешение необходимы, поэтому health_check и все остальные инструменты остаются работоспособными даже до предоставления полных разрешений.

Настройка

uv tool install entraadm-mcp
# or
pip install entraadm-mcp

Конфигурация

Установите три переменные app-only для продакшена/неавтоматического использования:

export ENTRAADM_TENANT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_SECRET=your-client-secret

Или оставьте все три неустановленными и сначала выполните az login для локальной разработки.

Необязательно:

# Default page cap for the log-scanning tools (1-50, default 5).
export ENTRAADM_MAX_PAGES_DEFAULT=5

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

Claude Code (плагин)

/plugin marketplace add shigechika/entraadm-mcp
/plugin install entraadm-mcp@entraadm-mcp

Claude Code (вручную)

Добавьте в .mcp.json:

{
  "mcpServers": {
    "entraadm-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["entraadm-mcp"],
      "env": {
        "ENTRAADM_TENANT_ID": "${ENTRAADM_TENANT_ID:-}",
        "ENTRAADM_CLIENT_ID": "${ENTRAADM_CLIENT_ID:-}",
        "ENTRAADM_CLIENT_SECRET": "${ENTRAADM_CLIENT_SECRET:-}"
      }
    }
  }
}

Прямое выполнение

entraadm-mcp

Параметры CLI

Примечания

• Контракт покрытия. Каждый результат, который проходит по разбитой на страницы коллекции Graph, содержит логическое значение capped, когда его окно не было полностью просканировано — частичное сканирование никогда не выдаётся за исчерпывающее.

• found: false — это не ошибка. get_user и get_user_auth_methods отвечают на несуществующую учётную запись с {"found": false, ...}, а не с ключом error — опечатка в userPrincipalName никогда не должна выглядеть как сбой этого сервера.

• Хранение. Entra ID P1 хранит журналы входа и аудита каталога в течение 30 дней. Окно за пределами этого срока возвращает пустой результат, а не ошибку.

Разработка

uv sync --dev
uv run pytest -v
uv run ruff check .
uv run ruff format --check .

Живой смоук-тест

uv run python scripts/smoke_test.py

Только чтение, без вывода полезных данных (только имена инструментов/статусы/количество строк) и ограничено (небольшие явные окна/лимиты страниц) — здесь ничего не записывается в тенант и не сканируется более чем за день журналов.

Релиз

Этот репозиторий использует release-please на основе Conventional Commits. Объедините PR с feat:/fix: в main, и release-please откроет (или обновит) PR релиза; объединение этого PR создаёт тег релиза и запускает конвейер публикации (PyPI, MCP Registry).

Лицензия

MIT